{mode === "edit" ? ( ) : ( )}

); }; export const BlogArticleFormLayout = ({ contentTypeId, itemId, }: ContentFormLayoutProps) => { const { skeleton } = useContentForm(); if (skeleton) return ; return ( }> ); }; ``` A few things that keep it smooth: - **Copy the real wrappers.** Same outer `div`, same padding, same `max-w-*`, same breakpoints. A skeleton that is 20 pixels shorter still makes the page jump. - **Branch on `mode`.** The create form often looks different, for example an empty upload area instead of a cover image and other buttons in the header. - **Call `markHeaderRendered()`** when the skeleton draws its own header, so the development warning about a missing `ContentFormHeader` stays quiet. - **Mark the fields as rendered in the fallback.** While the lazy editor loads, the real form is up, so the skeleton tells it that the layout will place every field. Without it, the console warns about missing fields for a moment. - **Start loading the editor from the skeleton.** The `useEffect` above fetches the editor's code while the record is still loading, so the fallback is rarely seen at all. - **Use `Skeleton` from `@vitnode/core/components/ui/skeleton`** and the Tailwind spacing scale, so placeholders match the theme in light and dark mode. ## Check the result [#check-the-result] Save the definition, restart `pnpm dev` and open **AdminCP → Example → Articles**. The API validates sorting and form input against the same definition, so the restart makes sure both sides read the new `admin` options. Next, give the screens the permissions they need in [Production checklist](/docs/content-engine/production), or read every option in the [reference](/docs/content-engine/reference). # Caching (/docs/content-engine/caching) The Content Engine does not cache public reads. Every request to a [public API](/docs/content-engine/public-api) route queries Postgres, and the response carries no `Cache-Control` header: ```bash curl -si "http://localhost:3000/api/@vitnode/example/content/articles?first=1" | head -4 ``` ```text HTTP/1.1 200 access-control-allow-credentials: true content-type: application/json cross-origin-opener-policy: same-origin ``` So a published article shows up on the next request, with nothing to expire. Add caching where it pays off: | Where the content is read | Cache with | Expire it with | | --------------------------------------- | --------------------------------------- | ----------------------------------------------------- | | A page of your VitNode app | TanStack Query, warmed in the loader | Its `staleTime`, or `invalidateQueries` after a write | | The HTML of a public page in your app | [Page cache](/docs/dev/cache/pages) | Automatic: every content write invalidates it | | A separate front end with its own cache | That front end's tag cache | `content.revalidateOrigins` and the cache tags below | | Your own Hono route | [`c.get("cache")`](/docs/dev/cache/api) | `c.get("cache").delete(key)` after a write | ## Cache a public list in the app [#cache-a-public-list-in-the-app] Wrap the fetcher call in `queryOptions` and warm it in the route loader, exactly as in [Cache app data](/docs/dev/cache/app). Use `defineRoute` from `@vitnode/core/tanstack/plugin-routes`, because its loader context has the `queryClient`: ```tsx title="latest-articles.tsx" import { queryOptions } from "@tanstack/react-query"; import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { defineRoute } from "@vitnode/core/tanstack/plugin-routes"; import { z } from "zod"; const zodArticleCard = z.object({ excerpt: z.string().nullable(), slug: z.string(), title: z.string(), }); export const latestArticlesQuery = () => queryOptions({ queryKey: ["@vitnode/example", "articles", "latest"], queryFn: async () => { const response = await fetcher({ plugin: "@vitnode/example", method: "get", module: "content/articles", path: "/", args: { query: { first: 5 } }, }); if (response.status !== 200) { throw new Error(`Loading articles answered ${response.status}.`); } const { edges } = await response.json(); return z.array(zodArticleCard).parse(edges); }, }); export const route = defineRoute({ load: async ({ context }) => { await context.queryClient.query({ ...latestArticlesQuery(), staleTime: 60_000, }); }, }); ``` Each server render starts with an empty query client, so a full page load is always fresh. The `staleTime` only decides how long a visitor's open tab reuses the list during client-side navigation. `staleTime: "static"` keeps it until the tab reloads. Publishing in the AdminCP refreshes the AdminCP's own list, item and search queries. It cannot reach a visitor's browser, so pick a `staleTime` you are happy to wait out. For your own write routes, call `queryClient.invalidateQueries({ queryKey: ["@vitnode/example", "articles"] })` after the write. Public routes also send an `x-vitnode-cache-tags` header naming the record they read, such as `content:blog.post:item:3`, or the content type for a list. The page cache stores a page with these tags and invalidates it after every write, hard for a hide, delete, unpublish or slug change. [How cached pages stay fresh](/docs/dev/cache/pages-invalidation#content-engine-invalidation) explains the rules. ## Cache tags [#cache-tags] When a front end caches public reads under tags, it needs to know which tags a write affects. `@vitnode/core/content` exports pure string builders for that. They read nothing and need no server: | Builder | Example for `example.article` | | --------------------------------------------------- | ------------------------------------------------------- | | `contentPublicListTag(typeId, locale?)` | `content:example.article:list` | | `contentPublicItemTag(typeId, id, locale?)` | `content:example.article:item:3` | | `contentPublicSlugTag(typeId, slug, locale?)` | `content:example.article:slug:hello-content-engine` | | `contentDeliveryTag(typeId, id, locale?)` | `content:example.article:delivery:3` | | `contentDeliveryRedirectTag(typeId, slug, locale?)` | `content:example.article:redirect:hello-content-engine` | | `contentDeliverySitemapTag(typeId, locale?)` | `content:example.article:sitemap` | A locale goes after the kind, so a localized type's Polish list is `content:example.localized-article:list:pl`. An id goes in as text, so a [uuid or bigint](/docs/content-engine/id-strategy) record's item tag carries its exact UUID or decimal string. `contentInvalidationTags` turns a description of one write into the exact tags to expire. Publishing article `3` returns all six tags above: ```ts title="revalidate.ts" import { contentInvalidationTags } from "@vitnode/core/content"; const tags = contentInvalidationTags({ contentTypeId: "example.article", id: 3, slugs: ["hello-content-engine"], wasPublic: false, isPublic: true, delivery: { sitemap: { contentChanged: true, indexChanged: true } }, }); ``` A write to a record that was a draft before and after returns `[]`, because no public reader ever saw it. On a slug change, pass both slugs so the old URL stops resolving and the new one starts. ## Notify a separate front end [#notify-a-separate-front-end] If another app renders your content and caches it, list its origin in the API config: ```ts title="apps/api/src/vitnode.api.config.ts" export const vitNodeApiConfig = buildApiConfig({ content: { revalidateOrigins: ["https://www.example.com"], // [!code ++] }, }); ``` VitNode then sends a `POST` to `{origin}/api/vitnode/content/revalidate` in these cases: | Change | Notifies origins | | ------------------------------------------------------------------------------------------- | ---------------------------------------------- | | A [scheduled](/docs/content-engine/editorial#schedule-publishing) publish or unpublish runs | Yes | | A record is [hidden or unhidden](/docs/content-engine/content-visibility) | Yes, when that changes what the public can see | | A publish, unpublish, edit or delete from the AdminCP or the API | No | Hiding a draft notifies nobody, because nothing public changed. For the changes that send nothing, a front end that caches must expire entries on its own timer, or from a listener for the [content events](/docs/content-engine/events). The request carries: - `Authorization: Bearer `, the same secret that runs cron jobs. - `x-vitnode-timestamp`, the send time in milliseconds. - A JSON body with the `contentInvalidationTags` input plus `mode`, which is always `"immediate"` for a scheduled run, a hide and an unhide. The secret travels with the request, so outside development each origin must use `https`. Plain `http` is allowed only for `localhost` and `127.0.0.1`. VitNode sends nothing while `CRON_SECRET` is unset or still the default. It tries each origin twice and does not retry a `403`, which it reads as a wrong secret. ### Build the revalidate endpoint [#build-the-revalidate-endpoint] The endpoint lives in your front end, not in VitNode. Before you expire anything, check the bearer in constant time and refuse a timestamp more than 5 minutes off, so a captured request cannot be replayed later: ```ts title="is-trusted-revalidation.ts" import { createHash, timingSafeEqual } from "node:crypto"; const MAX_SKEW_MS = 5 * 60 * 1000; const digest = (value: string) => createHash("sha256").update(value).digest(); export const isTrustedRevalidation = (request: Request): boolean => { const secret = process.env.CRON_SECRET; if (!secret) return false; const bearer = /^Bearer (.+)$/.exec( request.headers.get("authorization") ?? "", )?.[1]; if (!bearer || !timingSafeEqual(digest(bearer), digest(secret))) return false; const sentAt = Number(request.headers.get("x-vitnode-timestamp")); return ( Number.isFinite(sentAt) && Math.abs(Date.now() - sentAt) <= MAX_SKEW_MS ); }; ``` Hashing both values first gives `timingSafeEqual` two buffers of the same length. Answer `403` when the check fails. Otherwise pass the body to `contentInvalidationTags`, expire those tags in your cache and answer with any `2xx`. # Containers on the frontend (/docs/content-engine/container-frontend) This guide builds the member-facing side of the example plugin's boards: a `/boards` page with the nested board tree, a `/boards/:slug` page that lists the discussions of a board and every board below it, and a board picker on the "Start a discussion" form. The finished pages are in `plugins/example/src/pages/`, in the `board-*` and `discussion-*` files. The code below is the same, with some styling trimmed. ## Before you begin [#before-you-begin] You need a container collection with `publicApi`, and a content type whose `field.container()` is public, filterable and writable on create, as set up in [Containers](/docs/content-engine/containers#add-a-container-collection). The example's collection has `publicApi.path: "boards"`, so the fetcher's module is `content/boards`. The collection's public routes are read-only and need no session: | Route | Returns | | ----------------- | ---------------------------------------------------------------------------------------------- | | `GET /` | `{ items }`: every container in tree order. `?parent=root` or `?parent={id}` returns one level | | `GET /{idOrSlug}` | `{ container, ancestors, children }`: ancestors root first, direct children in order | Each item is `{ id, parentId, name, slug, position, depth, metadata }`, where `metadata` holds only `publicApi.fields`. An unknown container or `parent` answers `404`. A numeric segment is read as an id, anything else as a slug. ### Add the routes [#add-the-routes] Register the two board pages in `src/routes.ts`, and give the create page a `search` parser so it can read `?board=`. A `pendingComponent` is drawn while the loader runs, so import it directly rather than through `lazy()`: ```ts title="plugins/example/src/routes.ts" // [!code ++:4] import { FeedPendingSkeleton, RoutePendingSkeleton, } from "@vitnode/core/tanstack/pending"; import { boardSearch } from "./pages/board-search"; // [!code ++] import { discussionNewSearch } from "./pages/discussion-search"; // [!code ++] export const routes = definePluginRoutes([ // [!code ++:13] page("/boards", { component: lazy(() => import("./pages/boards-page")), messages: ["@vitnode/example.boards"], pendingComponent: RoutePendingSkeleton, }), page("/boards/:slug", { component: lazy(() => import("./pages/board-page")), messages: ["@vitnode/example.boards"], pendingComponent: FeedPendingSkeleton, search: boardSearch, }), page("/discussions/new", { component: lazy(() => import("./pages/discussion-new-page")), messages: ["@vitnode/example.discussions"], requires: "authenticated", search: discussionNewSearch, // [!code ++] }), ]); ``` `boardSearch` keeps a valid `cursor` for paging through discussions, and `discussionNewSearch` keeps a positive `board` id. Both are small functions in `board-search.ts` and `discussion-search.ts`. The strings live under `@vitnode/example.boards` in `src/locales/en.json`. ### Load the tree [#load-the-tree] Create a helper that reads every board. The list comes back in tree order, flat, so one request loads the whole tree: ```ts title="plugins/example/src/pages/boards-data.ts" import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { CONFIG_PLUGIN } from "@/const"; export const fetchBoards = async () => { const res = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "get", module: "content/boards", path: "/", args: { query: {} }, }); if (res.status !== 200) throw new Error("Loading the boards failed."); const { items } = await res.json(); return items; }; export type Board = Awaited>[number]; const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i; export const boardColor = (board: Pick): null | string => typeof board.metadata.color === "string" && HEX_COLOR.test(board.metadata.color) ? board.metadata.color : null; ``` `Board` is inferred from the API, so `board.metadata.color` is typed as `string | null` from the definition's fields, and `board.metadata.locked` is a compile error because `locked` is not public. `boardColor` accepts only a hex value before it goes into a `style` attribute, because an admin typed it. ### Render the tree [#render-the-tree] `contentContainerTree` from `@vitnode/core/content` nests a tree-ordered list: each node gets a `children` array. Render it recursively as nested lists inside a labelled `nav`, so screen readers announce the structure: ```tsx title="plugins/example/src/pages/board-tree.tsx" import type { ContentContainerTreeNode } from "@vitnode/core/content"; import type { Board } from "./boards-data"; import { boardHref } from "./board-search"; import { boardColor } from "./boards-data"; export const BoardColorDot = ({ board }: { board: Board }) => { const color = boardColor(board); return ( ); }; const BoardTreeItems = ({ nodes, }: { nodes: ContentContainerTreeNode[]; }) => (

{node.name} {node.metadata.description ? ( {node.metadata.description} ) : null} {node.children.length > 0 ? (

) : null}

); export const BoardTree = ({ label, nodes, }: { label: string; nodes: ContentContainerTreeNode[]; }) => ( ); ``` `contentContainerTree` keeps the server's order, so siblings appear in the order staff arranged them. It works on any rows with `id` and `parentId`, including the AdminCP records. ### Add the boards page [#add-the-boards-page] The route's `load` fetches and nests the tree, and the page shows it, or an empty state when no board exists yet: ```tsx title="plugins/example/src/pages/boards-page.tsx" import { contentContainerTree } from "@vitnode/core/content"; import { definePluginRoute, type PluginRoutePageProps, } from "@vitnode/core/routing"; import { useTranslations } from "use-intl"; import { BoardTree } from "./board-tree"; import { fetchBoards } from "./boards-data"; const loadBoards = async () => ({ tree: contentContainerTree(await fetchBoards()), }); type BoardsPageData = Awaited>; export const route = definePluginRoute({ load: loadBoards, head: ({ t }) => ({ description: t("@vitnode/example.boards.desc"), title: t("@vitnode/example.boards.title"), }), }); const BoardsPage = ({ loaderData }: PluginRoutePageProps) => { const t = useTranslations("@vitnode/example.boards"); return (

{t("title")}

{loaderData.tree.length === 0 ? (

{t("empty.desc")}

) : ( )}

); }; export default BoardsPage; ``` The example's page also has a breadcrumb, a **New discussion** button and an `Empty` state with an icon. ### Add the board page [#add-the-board-page] `/boards/:slug` makes two requests. The detail route returns the board, its ancestors for the breadcrumb and its child boards. The discussions list is filtered by the board, and `includeDescendants: "true"` widens the filter to every board below it, so **Frontend** also lists what was posted in **React**: ```tsx title="plugins/example/src/pages/board-page.tsx" import { contentPageItem } from "@vitnode/core/tanstack/content"; import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { z } from "zod"; import { CONFIG_PLUGIN } from "@/const"; import type { BoardSearch } from "./board-search"; const zodDiscussionRow = z.object({ id: z.number(), publishedAt: z.string().nullable(), slug: z.string().nullable(), title: z.string(), }); const loadBoard = async (idOrSlug: string, { cursor }: BoardSearch) => { const detail = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "get", module: "content/boards", path: "/{idOrSlug}", args: { params: { idOrSlug: encodeURIComponent(idOrSlug) } }, }); if (detail.status !== 200 && detail.status !== 404) { throw new Error("Loading the board failed."); } // A 404 becomes the route's not-found page. const { ancestors, children, container } = contentPageItem( detail.status === 200 ? await detail.json() : null, ); const filters = { board: String(container.id), includeDescendants: "true", }; const list = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "get", module: "content/discussions", path: "/", args: { query: { ...filters, first: "20", ...(cursor ? { cursor } : {}) }, }, }); if (list.status !== 200) throw new Error("Loading the discussions failed."); const { edges, pageInfo } = await list.json(); return { ancestors, children, container, discussions: z.array(zodDiscussionRow).parse(edges), isFirstPage: cursor === undefined, nextCursor: pageInfo.hasNextPage ? pageInfo.endCursor : null, }; }; ``` - The filter parameter is named after the field, `board`, and works only because `board` is in `publicApi.filterableFields`. Without `includeDescendants`, it matches that one board. - Filter parameters are not part of the inferred query type yet, so they are spread in from a small object instead of written as literal keys. - An unknown board id in the filter answers `404`, not an empty list, so a stale link never looks like an empty board. - `nextCursor` goes into `?cursor=` for an **Older discussions** link. Pass it back unchanged. Declare the trail as a breadcrumb group, one crumb per ancestor, and give the route a `notFound` component for the 404: ```tsx title="plugins/example/src/pages/board-page.tsx" export const route = definePluginRoute({ load: async ({ params, search }) => await loadBoard(params.slug, search), head: ({ loaderData }) => ({ description: loaderData?.container.metadata.description ?? undefined, title: loaderData?.container.name, }), breadcrumb: { group: ({ loaderData }) => ( <> {loaderData.ancestors.map(ancestor => ( {ancestor.name} ))} {loaderData.container.name} ), }, notFound: BoardNotFound, }); ``` The page renders the children with the same `BoardTree`, the discussions as a list of links, and a **New discussion** link to `/discussions/new?board={container.id}`. See the full component in `board-page.tsx`. ### Let members pick a board [#let-members-pick-a-board] Load the same tree for the create page and turn it into select options, indented by depth so the select reads like the tree: ```tsx title="plugins/example/src/pages/discussion-new-page.tsx" const loadBoardOptions = async () => (await fetchBoards()).map(board => ({ label: `${"— ".repeat(board.depth - 1)}${board.name}`, value: String(board.id), })); export const route = definePluginRoute({ load: loadBoardOptions, }); ``` Add the board to the form schema. A select works with strings, so the ids become a `z.enum`, preselected from `?board=` when it names a real board: ```tsx title="plugins/example/src/pages/discussion-form.tsx" const createDiscussionCreateFormSchema = ( t: ( key: "board.required" | "body.required" | "title.max" | "title.min", ) => string, ids: [string, ...string[]], selected: string | undefined, ) => { const board = z.enum(ids, { error: t("board.required") }); return createDiscussionFormSchema(t, { body: emptyRichTextDocument(), title: "", }).extend({ board: selected !== undefined && ids.includes(selected) ? board.default(selected) : board, }); }; ``` Render it with `AutoFormSelect` before the title and body fields: ```tsx title="plugins/example/src/pages/discussion-form.tsx" { id: "board", component: props => ( ), }, ``` On submit, send the board as a number inside `values`, like every other writable field: ```tsx title="plugins/example/src/pages/discussion-new-page.tsx" const onSubmit: AutoFormOnSubmit = async ( { board, ...values }, form, ) => { const res = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "post", module: "content/discussions", path: "/", args: { body: { values: { ...values, board: Number(board) } } }, }); if (res.status === 201) { // Redirect to the new discussion, as in Public write frontend. return; } await rejectDiscussion(res, form); }; ``` The server never trusts the id. It reads the board back inside the write's transaction and checks that it belongs to `example.boards`. A board that was deleted while the form was open, or one from another collection, answers `400` with an issue on the `board` field: ```json { "code": "CONTENT_INVALID_INPUT", "contentTypeId": "example.discussion", "issues": [ { "code": "unavailable", "field": "board", "message": "The selected container does not exist." } ] } ``` `useDiscussionRejection` from [Public write frontend](/docs/content-engine/public-write-frontend#build-the-shared-form) already puts field issues under their field. Add `"board"` to its list of fields and a board-specific message for `unavailable`: ```tsx title="plugins/example/src/pages/discussion-form.tsx" const DISCUSSION_FIELDS = ["title", "body", "board"] as const; // [!code highlight] const messageOf = (code: string, field?: DiscussionField) => t( field === "board" && code === "unavailable" ? "issues.board_unavailable" : isKnownIssueCode(code) ? ISSUE_MESSAGE_KEYS[code] : "invalid", ); ``` The edit form stays as it was. A container field cannot be in `publicWrite.update.fields`, so moving a discussion to another board is a staff edit in the AdminCP. ## Check the result [#check-the-result] 1. Create **Frontend** with **React** inside it in the AdminCP, then open `/boards`. Both boards show, **React** nested under **Frontend**. 2. Open **React** and click **New discussion**. The form opens with **— React** preselected. Post it. 3. Open `/boards/frontend`. The discussion is listed there too, because of `includeDescendants`, and the breadcrumb ends with **Boards** and **Frontend**. 4. Open `/boards/nope`. The not-found page shows. ## Errors to handle [#errors-to-handle] | Request | Answer | What the page does | | ------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------ | | `GET content/boards/{idOrSlug}` for an unknown board | `404` | `contentPageItem(null)` renders the route's `notFound` | | `GET content/boards?parent={id}` for an unknown parent | `404` | Treat it like a missing board | | `GET content/discussions?board={id}` for an unknown board | `404` | Treat it like a missing board | | `POST content/discussions` with a missing, deleted or foreign board | `400`, issue on `board` | Show the message under the select | | `POST content/discussions` with no `board` at all | `400`, issue on `board` | The form's own `required` check catches it first | The [public write status codes](/docs/content-engine/public-write-api#status-codes) cover sign-in, permission and rate-limit answers, which work the same with or without containers. # Container hierarchy (/docs/content-engine/container-hierarchy) A container collection is a tree. This page explains the rules every change to that tree follows, whether it comes from the AdminCP or from your own code, and shows how to use the container service on the server. It uses the `example.boards` collection from [Containers](/docs/content-engine/containers). ## Depth [#depth] `depth` is 1 for a root, 2 for its children, and so on. `hierarchy.maxDepth` caps it and counts roots, so the example's `maxDepth: 3` allows **Frontend → React → Hooks** and nothing below **Hooks**. - The default is 5, the ceiling is 10. - `hierarchy: { enabled: false }` keeps every container at the root: a flat, ordered list. Any `parentId` is refused. - A move checks the whole subtree it carries. Moving a board that has children under a deep parent is refused if the deepest child would cross the limit. ## Ordering [#ordering] Siblings are ordered by `ordering.mode`: | Mode | Order | Reordering | | -------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | `manual` | `position`, the order staff drag them into | Allowed. `position` is zero-based among siblings and kept as `0..n-1` | | `alphabetical` | `name`, case-insensitive | Ignored. A new or moved container goes last by position, but reads sort by name. Moving to another parent still works | Both modes break ties by `id`, so two reads of the same tree always agree. ## Moves and reorders [#moves-and-reorders] One operation covers both: `move(id, { parentId, position })`. `parentId: null` moves to the root. `position` is the index among the new siblings **after** the container has left its old place. So moving the first of three siblings to `position: 2` puts it last. A move is refused, and changes nothing, when: | Code | Status | When | | ----------------- | ------ | --------------------------------------------------------------------------------------- | | `cycle` | 400 | The new parent is the container itself or one of its descendants | | `parentNotFound` | 400 | The new parent does not exist in this collection | | `maxDepth` | 400 | The container or its deepest descendant would be too deep, or the hierarchy is disabled | | `invalidPosition` | 400 | `position` is negative or past the end of the sibling list | | `notFound` | 404 | The container does not exist | The old and the new sibling lists are both renumbered, so positions never have gaps. ## Safe deletion [#safe-deletion] Deleting never cascades. A container is deleted only when it is empty: - `hasChildren` (409): it still has child containers. Move or delete them first. - `hasContent` (409): a record of any content type that uses this collection still points at it. Move or delete those records first. The database enforces the same rules. Both `parentId` and every `field.container()` column are foreign keys with `ON DELETE RESTRICT`, so a delete can never orphan a board or a discussion, even if another request slips in between the check and the delete. The remaining siblings are renumbered to close the gap. ## Slugs [#slugs] A slug addresses one container of one collection, so `frontend` can exist once in `example.boards` and once in another collection. A slug you pass is normalized (lowercase ASCII, dashes) and must be free, or the write fails with `slugTaken`. A missing slug is derived from the name, with `-2`, `-3` and so on added until it is free. A slug that normalizes to nothing, such as `"!!!"`, fails with `slugEmpty`. ## Concurrent edits [#concurrent-edits] Two admins dragging boards at the same moment cannot corrupt the tree. Every write to a collection: 1. Takes a transaction-scoped Postgres advisory lock for that collection, so writes to one collection run one after another. Different collections never wait for each other. 2. Reads the whole tree inside the transaction, so it plans against what the previous write committed. 3. Checks every rule before changing a single row. A refused write leaves the tree exactly as it was. A collection holds at most 5,000 containers (`limitReached`, 409). The whole tree is read in one query, so a read costs the same at any depth and never runs one query per level. ## Use the service on the server [#use-the-service-on-the-server] `createContentContainerService` is the one way to read and change a collection. The AdminCP routes and the public routes both use it, so your code gets the same rules, cache expiry and events. Call it inside any Hono handler with the request context: ```ts title="plugins/example/src/api/modules/boards/archive.route.ts" import { buildRoute } from "@vitnode/core/api/lib/route"; import { createContentContainerService } from "@vitnode/core/content/server"; import { HTTPException } from "hono/http-exception"; import { z } from "zod"; import { CONFIG_PLUGIN } from "@/const"; import { boardContainers } from "@/content/boards"; export const archiveBoardRoute = buildRoute({ pluginId: CONFIG_PLUGIN.pluginId, adminStaffPermission: { module: "example_boards", permission: "can_edit" }, route: { method: "post", path: "/{id}/archive", description: "Move a board under the Archive board and lock it", request: { params: z.object({ id: z.coerce.number().int().positive() }) }, responses: { 200: { description: "Board archived" }, 404: { description: "Board or Archive not found" }, }, }, handler: async c => { const { id } = c.req.valid("param"); const boards = createContentContainerService(c, { definition: boardContainers, pluginId: CONFIG_PLUGIN.pluginId, }); const archive = await boards.findBySlug("archive"); if (!archive) { throw new HTTPException(404, { message: "Create an Archive board first.", }); } const siblings = await boards.children(archive.id); await boards.move(id, { parentId: archive.id, position: siblings.length }); await boards.update(id, { metadata: { locked: true } }); return c.json({ message: "Board archived." }, 200); }, }); ``` Refused writes throw a `ContentContainerError` with `code`, `status` (400, 404 or 409) and a readable `detail`. The generated AdminCP routes turn it into a response body of `{ code, message }`, typed by `zodContentContainerError`. In your own route, catch it or let it surface as a 500. | Method | Returns | Behavior | | -------------------- | --------------------------- | ---------------------------------------------------------------------------------------------- | | `list()` | `Promise` | Every container, in tree order: each parent, then its subtree | | `children(parentId)` | `Promise` | Direct children in sibling order. `null` returns the roots | | `ancestors(id)` | `Promise` | Every container above `id`, root first. Empty for a root or an unknown id | | `descendantIds(id)` | `Promise` | `id` plus every id below it, or `null` when `id` does not exist | | `findById(id)` | `Promise` | One container | | `findBySlug(slug)` | `Promise` | One container by its exact slug | | `create(input)` | `Promise` | `{ name, slug?, parentId?, position?, metadata? }`. Goes last when `position` is left out | | `update(id, input)` | `Promise` | `{ name?, slug?, metadata? }`. `metadata` is a partial patch, validated against the definition | | `move(id, input)` | `Promise` | `{ parentId, position }`, as described in [Moves and reorders](#moves-and-reorders) | | `delete(id)` | `Promise` | Deletes an empty container, as described in [Safe deletion](#safe-deletion) | | `toPublic(record)` | `PublicRecord` | Drops every metadata field not in `publicApi.fields` | A record is `{ id, parentId, name, slug, position, depth, metadata, createdAt, updatedAt }`, with `metadata` typed from the definition's fields. `ContentContainerRecord` and `ContentContainerPublicRecord` from `@vitnode/core/content` name those types. The tree helpers the service uses are pure and browser-safe, exported from `@vitnode/core/content`: `contentContainerTree` nests a list, `orderContentContainers` sorts rows into tree order with their depth, and `contentContainerAncestors` and `contentContainerSubtreeIds` walk it. ## Events [#events] Each successful write emits one event after its transaction commits. A write that is refused emits nothing, and an update that changes nothing emits nothing. | Event | Payload | | --------------------------- | --------------------------------------------------------------------------- | | `content.container.created` | `{ definitionId, pluginId, containerId, parentId }` | | `content.container.updated` | `{ definitionId, pluginId, containerId, parentId, changedFields }` | | `content.container.moved` | `{ definitionId, pluginId, containerId, parentId, fromParentId, position }` | | `content.container.deleted` | `{ definitionId, pluginId, containerId, parentId }` | The names are shared by every collection, so filter on `definitionId`: ```ts title="plugins/example/src/api/lib/events.ts" import { buildEventListener } from "@vitnode/core/api/lib/events"; export const boardMovedListener = buildEventListener({ event: "content.container.moved", name: "log-board-moves", handler: async (c, payload) => { if (payload.definitionId !== "example.boards") return; await c .get("log") .debug( `Board ${payload.containerId} moved from ${payload.fromParentId ?? "the root"} to ${payload.parentId ?? "the root"}`, ); }, }); ``` `changedFields` names `name`, `slug` and the metadata fields whose value actually changed. A reorder among siblings is a `moved` event with the same `fromParentId` and `parentId`. Register listeners as described in [Events](/docs/dev/events). [Built-in events](/docs/dev/events/built-in-events#content-container-events) has the field-by-field payloads. Every write also expires the [page cache](/docs/content-engine/caching) entries that read the collection, including pages that list content filtered by one of its containers, so a renamed board shows its new name without a manual purge. Next, build pages on top of the tree in [Containers on the frontend](/docs/content-engine/container-frontend). # Containers (/docs/content-engine/containers) A container is a place a record lives in: one forum board, one blog section, one knowledge-base category. You declare a **collection** of containers once in code, admins build its tree in the AdminCP, and each record of a content type points at exactly one container through `field.container()`. This guide follows the example plugin: a `example.boards` collection, and discussions (`example.discussion`) filed into it. ## Containers or a content type? [#containers-or-a-content-type] A category could also be a content type with a [relation](/docs/content-engine/relations). Pick a container when the thing organizes content rather than being content itself: | | Container collection | Content type | | ------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- | | Declared with | `defineContentContainer` | `defineContentType` | | Storage | One shared core table, `core_content_containers`. No migration of its own | Its own table, with a migration | | Shape | A tree with parents, sibling order and a depth limit | Flat records | | Fields | A few scalars (`text`, `textarea`, `number`, `boolean`, `enum`) | Every field kind | | Drafts, revisions | No. A container exists or it does not | Optional `publication`, `editorial` and friends | | Linked from records | `field.container()`, at most one per content type | `field.relation()`, as many as you need | | Public filter | `?board=4`, and `includeDescendants=true` for a whole subtree | `?category=4`, exact match only | A record belongs to one container. For anything else it points at, such as tags, keep using relations. ## Add a container collection [#add-a-container-collection] You need a content type to file into containers, like `example.discussion` from [Public write](/docs/content-engine/public-write#enable-public-writing). ### Define the collection [#define-the-collection] Create `src/content/boards.ts`. The definition describes the collection; each board is a row an admin creates later: ```ts title="plugins/example/src/content/boards.ts" import { defineContentContainer, field } from "@vitnode/core/content"; export const boardContainers = defineContentContainer({ id: "example.boards", fields: { description: field.textarea({ maxLength: 500, nullable: true }), color: field.text({ maxLength: 7, nullable: true }), icon: field.text({ maxLength: 64, nullable: true }), locked: field.boolean({ defaultValue: false }), }, hierarchy: { maxDepth: 3 }, ordering: { mode: "manual" }, publicApi: { path: "boards", fields: ["description", "color", "icon"], }, admin: { path: "example/boards" }, }); ``` Every container already has `id`, `parentId`, `name`, `slug`, `position` and `depth`. `fields` adds your own values, stored in a `metadata` column and validated against the definition on every write. `locked` is not in `publicApi.fields`, so it never leaves the server. | Name | Type | Required | Default | Description | | ----------- | ------------------------------------------- | -------- | -------------------------------- | ----------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | | `plugin.collection`, lowercase and dot separated. Every row stores it, so never rename it | | `fields` | `field.*()` map | No | `{}` | Extra values per container. `text`, `textarea`, `number`, `boolean` and `enum` only | | `hierarchy` | `{ enabled?: boolean; maxDepth?: number }` | No | `{ enabled: true, maxDepth: 5 }` | `maxDepth` counts levels, roots included, from 2 to 10. `enabled: false` makes a flat list | | `ordering` | `{ mode?: "manual" \| "alphabetical" }` | No | `{ mode: "manual" }` | How siblings are sorted. See [Hierarchy and ordering](/docs/content-engine/container-hierarchy) | | `publicApi` | `{ path: string; fields?: string[] }` | No | off | Read-only public routes at `/api/{pluginId}/content/{path}` | | `admin` | `{ path?; permissionModule?; navigation? }` | No | see below | The AdminCP screen and its staff permissions | `admin.path` defaults to the id with dots turned into slashes (`example/boards`), so the screen opens at `/admin/containers/example/boards`. `admin.permissionModule` defaults to the snake-cased id (`example_boards`), and `admin.navigation: false` hides the sidebar entry. ### Point the content type at it [#point-the-content-type-at-it] Add one `field.container()` to the content type. List it in `publicApi.fields` to return it, in `filterableFields` to filter by it, and in `publicWrite.create.fields` to let members pick it: ```ts title="plugins/example/src/content/discussion.ts" import { boardContainers } from "@/content/boards"; // [!code ++] export const discussionContentType = defineContentType({ id: "example.discussion", tableName: "example_discussions", fields: { title: field.text({ required: true, minLength: 3, maxLength: 200 }), slug: field.slug({ source: "title" }), body: field.richText({ required: true }), author: field.user(), board: field.container({ definition: boardContainers, required: true }), // [!code ++] }, publicApi: { path: "discussions", fields: ["id", "title", "slug", "body", "board", "publishedAt"], // [!code highlight] filterableFields: ["board"], // [!code ++] }, publicWrite: { ownership: { field: "author" }, create: { fields: ["title", "body", "board"], status: "published" }, // [!code highlight] update: { fields: ["title", "body"] }, }, }); ``` The column is an `integer` foreign key to `core_content_containers.id` with `ON DELETE RESTRICT`, plus an index on `(board, publishedAt)`. Every write checks that the id belongs to `example.boards`, not just that it exists. All options are in [Fields](/docs/content-engine/fields#container). ### Register the collection on the API [#register-the-collection-on-the-api] Pass the definition to both content modules. The admin module adds the staff routes and the `example_boards` permissions; the public module adds the read routes: ```ts title="plugins/example/src/api/modules/admin/admin.module.ts" import { boardContainers } from "@/content/boards"; // [!code ++] buildContentAdminModule({ pluginId: CONFIG_PLUGIN.pluginId, containers: [boardContainers], // [!code ++] contentTypes: [articleContent, discussionContent], }), ``` ```ts title="plugins/example/src/config.api.ts" buildContentPublicModule({ pluginId: CONFIG_PLUGIN.pluginId, containers: [boardContainers], // [!code ++] contentTypes: [articleContent, discussionContent], }), ``` A content type whose `field.container()` names a collection no plugin registers stops the API at startup. Registering the same definition object in both modules is fine. ### Register the AdminCP screen [#register-the-admincp-screen] Add the collection to `containers` in both AdminCP files, next to your content types. `icon` is optional and defaults to a folder icon: ```tsx title="plugins/example/src/admin/nav.tsx" import { FolderTreeIcon } from "lucide-react"; // [!code ++] import { boardContainers } from "@/content/boards"; // [!code ++] // [!code ++:4] export const exampleBoardsNav = { definition: boardContainers, icon: , }; export const adminNav = { pluginId: CONFIG_PLUGIN.pluginId, containers: [exampleBoardsNav], // [!code ++] contentTypes: [exampleArticleNav, exampleDiscussionNav], } satisfies AdminNavPluginSource; ``` ```tsx title="plugins/example/src/admin/content.tsx" export const adminContent = { pluginId: CONFIG_PLUGIN.pluginId, containers: [exampleBoardsNav], // [!code ++] contentTypes: [exampleArticleNav, exampleDiscussionNav], } satisfies ContentFrontendPluginSource; ``` [Plugin files](/docs/content-engine/plugin-files) explains why the two files are separate. ### Add the labels [#add-the-labels] The AdminCP reads the collection's names from `{pluginId}.containers.{entity}`, where the entity is the id without its plugin prefix. The permission labels follow the permission module: ```json title="plugins/example/src/locales/en.json" { "@vitnode/example": { "containers": { "boards": { "label": "{count, plural, one {Board} other {Boards}}", "title": "Boards", "desc": "The board tree members file their discussions into.", "fields": { "description": "Description", "color": "Color", "icon": "Icon", "locked": "Locked" } } }, "content": { "discussion": { "fields": { "board": "Board" } } } }, "@vitnode/example:example_boards": "Boards", "@vitnode/example:example_boards:can_view": "View boards", "@vitnode/example:example_boards:can_create": "Create boards", "@vitnode/example:example_boards:can_edit": "Edit and move boards", "@vitnode/example:example_boards:can_delete": "Delete boards" } ``` Without labels, the screen falls back to a name derived from the id, such as "Boards". ### Build, migrate and restart [#build-migrate-and-restart] Run this from the workspace root, then restart `pnpm dev`: ```bash tab="bun" bun run build:plugins && bun run db:migrate ``` ```bash tab="pnpm" pnpm build:plugins && pnpm db:migrate ``` ```bash tab="npm" npm run build:plugins && npm run db:migrate ``` The collection itself needs no table: every definition shares `core_content_containers`. The migration only adds the `board` column to `example_discussions`. A required container field becomes a `NOT NULL` column. If the table already has rows, edit the generated migration to create a container and assign it before the `SET NOT NULL`, as the example's migration does with a "General" board. [Database](/docs/content-engine/database) covers editing migrations. ## Manage containers in the AdminCP [#manage-containers-in-the-admincp] Open **AdminCP → Example → Boards** (`/admin/containers/example/boards`). Staff need the collection's `can_view` permission to see it, and `can_create`, `can_edit` or `can_delete` for each action. - **The tree** shows every board with its children nested below it. Drag a board to reorder it among its siblings or to drop it inside another board. - **Create and edit** open a sheet with the name, the slug and the collection's own fields. A container created without a slug gets one derived from its name. - **The move menu** on each row does the same as dragging from the keyboard: **Move up**, **Move down**, **Move to top level** and **Move inside…**. - **Delete** works only on an empty board. A board with child boards or with discussions is refused with a message that says which one, and nothing changes. In a content type's generated form, a container field becomes a **picker** that lists the collection's tree, so staff can file a discussion into a board or move it to another one. A drag that breaks a rule, such as nesting a board deeper than `maxDepth` or dropping it inside its own child, is refused the same way. [Hierarchy and ordering](/docs/content-engine/container-hierarchy) lists every rule. ## Check the result [#check-the-result] Create a "Frontend" board with a "React" board inside it, then read the public tree: ```bash curl http://localhost:3000/api/@vitnode/example/content/boards ``` ```json { "items": [ { "id": 1, "parentId": null, "name": "Frontend", "slug": "frontend", "position": 0, "depth": 1, "metadata": { "description": "Everything in the browser", "color": "#2563eb", "icon": null } }, { "id": 2, "parentId": 1, "name": "React", "slug": "react", "position": 0, "depth": 2, "metadata": { "description": null, "color": null, "icon": null } } ] } ``` Items come in tree order: each parent, then its subtree. `metadata` holds only `publicApi.fields`, and a value nobody set is `null`. [Containers on the frontend](/docs/content-engine/container-frontend) turns this into pages. ## Definition errors [#definition-errors] `defineContentContainer` and the boot checks throw a `ContentEngineError` before the app serves a request: | Cause | Message starts with | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | An id that is not `plugin.collection` | `Container definition id "x" must look like "plugin.collection"` | | A field named `id`, `name`, `slug`, `depth`, `metadata` or another column | `Field "x" is reserved.` | | A field kind other than text, textarea, number, boolean or enum | `Field "x" is a "relation" field.` | | A field with `localized`, `unique` or `ai` | `Field "x" is` followed by the option and why containers refuse it | | `maxDepth` below 2 or above 10 | `hierarchy.maxDepth must be a whole number from 2 to 10.` | | `publicApi.fields` naming an unknown or built-in field | `publicApi.fields references unknown field "x".` | | Two collections with one id or one `admin.path` | `Duplicate container definition id` / `AdminCP path "x" is claimed by both` | | A collection and a content type sharing a public path or permission module | `Public path "x" is claimed by both` / `Permission module "x" is used by both` | | Two `field.container()` in one content type | `Content type declares 2 container fields` | | `field.container()` pointing at an unregistered collection | `Field "x" uses the container collection "y", which no plugin registers.` | | A container field in `publicWrite.update.fields` | `publicWrite.update.fields includes the container field "x".` | ## What's next [#whats-next] Per-container policies are planned, not shipped. Today every container behaves the same way. Containers are where per-place rules will live: a publishing mode per board (go live or wait as a draft), moderator approval, who may post or read in a board, and boards hidden from guests. The groundwork is in place. A public create already resolves the container on the server and hands it to `resolveContentPublicationPolicy`, so these policies can arrive without changing your routes or forms. - [Hierarchy and ordering](/docs/content-engine/container-hierarchy): depth, moves, safe deletion and the server-side service. - [Containers on the frontend](/docs/content-engine/container-frontend): a board tree, a board page and a create form with a board picker. # Hide content (/docs/content-engine/content-visibility) Hiding takes a record off the public site right away while it stays published. It disappears from the public API, its page, search and the sitemap, and unhiding brings it back with its original URL and publish date. Reach for it when a post has to go now and the questions can wait. This guide follows the blog plugin, whose articles can be hidden. | You want to | Use | | ---------------------------------------------------------------------- | --------------------------------------------------------------- | | Take a record down for now and put it back as it was | Hide | | Turn a record back into a draft to rework it before it goes live again | [Unpublish](/docs/content-engine/public-api#publish-an-article) | | Remove it for good | Delete | ## Before you begin [#before-you-begin] Hiding needs [`publication`](/docs/content-engine/public-api), because a record that is never public has nothing to hide from. ### Turn on visibility [#turn-on-visibility] The blog's article content type turns it on next to `publication`: ```ts title="plugins/blog/src/content/post.ts" export const blogPostContentType = defineContentType({ id: "blog.post", tableName: "blog_posts", publication: true, visibility: true, // [!code ++] // ... }); ``` `visibility` takes only `true` or `false`. Without `publication` it throws when the content type is defined. With it, `hiddenAt`, `hiddenBy` and `visibility` are reserved and cannot be field names. ### Build and migrate [#build-and-migrate] Run `pnpm build:plugins && pnpm db:migrate`, then restart `pnpm dev`. The migration adds two nullable columns to the main table. For the blog, `apps/api/migrations/20261011093549_content_visibility_id_strategies` contains: ```sql title="migration.sql (excerpt)" ALTER TABLE "blog_posts" ADD COLUMN "hiddenAt" timestamp; ALTER TABLE "blog_posts" ADD COLUMN "hiddenBy" integer; CREATE INDEX "blog_posts_hidden_by_idx" ON "blog_posts" ("hiddenBy"); ALTER TABLE "blog_posts" ADD CONSTRAINT "blog_posts_hiddenBy_core_users_id_fkey" FOREIGN KEY ("hiddenBy") REFERENCES "core_users"("id") ON DELETE SET NULL ON UPDATE CASCADE; ``` Existing records stay visible. `hiddenAt` is when the record was hidden and `hiddenBy` is the staff member who hid it. ### Label the permission [#label-the-permission] Visibility adds a `can_hide` permission, separate from `can_publish`, so a moderator can take records down without being able to publish. The blog labels it next to its other article permissions: ```json title="plugins/blog/src/locales/en.json" { "@vitnode/blog:posts:can_hide": "Hide and unhide articles" } ``` Grant it to the staff who should moderate in **AdminCP → Staff**. ### Hide an article [#hide-an-article] Open **AdminCP → Blog → Articles**, open the **More actions** menu of a published article and choose **Hide**. Confirm with **Yes, hide it**: A toast says the article is now hidden. The row keeps its **Published** badge, and its title gets an eye-off icon in front with an **Article hidden** tooltip. The **Visibility** filter in the list toolbar shows only hidden or only visible records, and it combines with the **Status** filter: The edit page shows the same icon before the title, an **Unhide** action (in the blog's editor, it lives in the ▾ menu next to **Save changes**) and a note that publishing a hidden record does not make it public: Choose **Unhide** in the same menu, or on the edit page, to bring the article back. In the database, hiding sets `blog_posts."hiddenAt"` and `"hiddenBy"`, and unhiding clears both. Cleaning up after a spam wave? Tick several articles and choose **Visibility → Hide** in the floating bar. The menu counts how many of them are still visible, such as **Hide 2 of 3**, and leaves the rest alone. **Unhide** works the same way. See [Bulk actions](/docs/content-engine/admincp#bulk-actions). ## What hiding does [#what-hiding-does] A record is public only when it is published, its `publishedAt` is not in the future, and it is not hidden. While a record is hidden: - The public API list leaves it out and its detail route answers `404`, in every language, including a language that falls back to the default one. - Its [page](/docs/content-engine/public-pages) answers `404`, and so do its old slugs instead of redirecting. - The [sitemap](/docs/content-engine/seo#sitemap) and `hreflang` alternates leave it out, and [site search](/docs/content-engine/search) marks its document private. - Signed [preview links](/docs/content-engine/editorial#preview-links) still work, and the AdminCP still shows it. ## Who can still see it [#who-can-still-see-it] Hidden doesn't mean gone for the people working on it. Signed in, a record's **authors**, its **editors** and its **moderators** still reach it: - **Authors** are the users in the content type's [`search.authorField`](/docs/content-engine/search), such as the blog's **Author** field. - **Editors** are staff with `can_edit` on the content type, such as `posts:can_edit` for the blog. - **Moderators** with the moderator permission `can_view_hidden` on a [reportable](/docs/dev/moderation/enable-reports) content type, in the record's scope when it has one. They need no AdminCP permission. The route tells whose record it is by its `id`, so `id` must be in `publicApi.fields`. For them: - The page opens with an eye-off icon before the title and a **This article is hidden** note, so nobody mistakes it for a live page. The response sends `noindex` and `Cache-Control: private, no-store`, so search engines and caches never keep it. - The detail route answers `200`, and `GET .../delivery/resolve/{slug}` returns `hidden: true`. - [Site search](/docs/content-engine/search) and the member timeline list it with the eye-off icon before its title and a tooltip like **Article hidden**. Everyone else, signed in or not, still gets a `404`. Old slugs never redirect to a hidden record, and the list, sitemap and `hreflang` alternates leave it out for everybody. Search learns that a record is hidden when it is hidden or unhidden. Records hidden before you updated VitNode show up for their authors and editors only after a reindex: **AdminCP → Advanced → Search**, then **Reindex** on the collection, such as `blog.post`. See [Search](/docs/content-engine/search). Hiding changes nothing else. `status` and `publishedAt` stay as they are, so unhiding a published record puts it back with its original date. Publishing, unpublishing and scheduled publishes never change visibility, so publishing a hidden record keeps it off the site until someone unhides it. Restoring a revision never changes visibility either. With [`editorial`](/docs/content-engine/editorial), hiding and unhiding raise the record's `version` and store a revision, shown as **Hidden** or **Unhidden** in the history. Hiding a record that is already hidden changes nothing: no write, no revision and no event. Hiding is per record. To take one language off the site, unpublish that translation instead. ## Hide from the API [#hide-from-the-api] The admin module has `POST /{id}/hide` and `POST /{id}/unhide`, such as `POST /api/@vitnode/blog/admin/content/posts/703/hide` for the blog. Both need `can_hide` and accept an optional body: ```json { "expectedVersion": 4 } ``` With `expectedVersion`, the call fails with `409` and `CONTENT_VERSION_CONFLICT` when someone saved the record meanwhile, like any [editorial write](/docs/content-engine/editorial#safe-concurrent-edits). Both routes answer `200` with `{ changed, row }`, where `changed` is `false` when the record was already in that state. A malformed id is `400` and a missing record is `404`. With `delivery.redirects`, unhiding can also fail with `409` when another record took the URL while this one was hidden. The admin list route accepts `?visibility=hidden` or `?visibility=visible`, and it combines with `?status=`. From your own code, `hide(id, options)` and `unhide(id, options)` exist on the services when visibility is on. See [Services](/docs/content-engine/services#hide-duplicate-and-content-ids). ## Events and caches [#events-and-caches] A hide emits `content.blog.post.hidden` with `{ actorUserId, contentId, hiddenAt }`, and an unhide emits `unhidden` with `{ actorUserId, contentId }`. Both update the search index and the delivery data. See [Events](/docs/content-engine/events). Front ends listed in [`content.revalidateOrigins`](/docs/content-engine/caching#notify-a-separate-front-end) are notified at once when a hide or unhide changes what the public can see. Hiding a draft notifies nobody, because nothing public changed. ## Check the result [#check-the-result] Hide the published "Second post", then request its page and its API entry: ```bash curl -o /dev/null -w "%{http_code}\n" "http://localhost:3000/blog/second-post" curl -o /dev/null -w "%{http_code}\n" "http://localhost:3000/api/@vitnode/blog/content/blog/second-post" ``` Both answer `404`, like a draft, and the article drops out of the blog list and the sitemap. In the AdminCP it is still **Published**. Unhide it, and the same requests answer `200` with the original `publishedAt`. Open the page while signed in as one of its authors, and it loads with the hidden note instead. # First content type (/docs/content-engine/create-a-content-type) This tutorial builds `example.category`, the content type behind **AdminCP → Example → Categories** in VitNode's example plugin. You write one definition, wire it into four small files, run one migration, and get a Postgres table, a list with a create form, staff-only API routes and four staff permissions. Categories have one field, so you spend your time on the wiring instead of naming things. Every snippet is copied from `plugins/example`, with unrelated content types trimmed out. Use your own plugin id wherever you see `@vitnode/example`. ## Before you begin [#before-you-begin] You need a plugin that your app already loads, with `src/config.api.ts`, `src/config.tsx` and a `src/const.ts` that exports the plugin id: ```ts title="plugins/example/src/const.ts" export const CONFIG_PLUGIN = { pluginId: "@vitnode/example" as const }; ``` [Create a plugin](/docs/dev/plugins/create) generates all three. You also need a running PostgreSQL database and an AdminCP account. ### Declare the content type [#declare-the-content-type] Create `src/content/category.ts`: ```ts title="plugins/example/src/content/category.ts" import { defineContentType, field } from "@vitnode/core/content"; export const categoryContentType = defineContentType({ id: "example.category", tableName: "example_categories", fields: { name: field.text({ required: true, minLength: 1, maxLength: 100 }), }, admin: { path: "example/categories", list: { columns: ["name", "createdAt"], orderableFields: ["name"], }, }, }); ``` - `id` is `plugin.entity`, lowercase and dot separated. The part after the first dot (`category`) names the translations and the permissions. - `tableName` is the Postgres table, in snake_case. - `admin.path` sets the AdminCP URL, `/admin/content/example/categories`. - `list.columns` may name your fields and the system columns `id`, `createdAt` and `updatedAt`. `orderableFields` makes the **Name** header sortable. You get a few things without asking: the list searches its text columns, the first text field becomes the record's title, and create and edit open in a dialog. Every field helper is listed in [Fields](/docs/content-engine/fields). ### Create the model [#create-the-model] Create `src/database/categories.ts`. `createContentModel` turns the definition into a Drizzle table, Zod schemas and a service: ```ts title="plugins/example/src/database/categories.ts" import { createContentModel } from "@vitnode/core/content/server"; import { categoryContentType } from "@/content/category"; export const categoryContent = createContentModel(categoryContentType); export const example_categories = categoryContent.table; ``` Export the table. Drizzle Kit finds tables by reading the exports of your plugin's built `dist/src/database/*.js` files, so a table nobody exports never reaches a migration. ### Add the staff API routes [#add-the-staff-api-routes] Create an `admin` module and pass the model to `buildContentAdminModule`: ```ts title="plugins/example/src/api/modules/admin/admin.module.ts" import { buildModule } from "@vitnode/core/api/lib/module"; import { buildContentAdminModule } from "@vitnode/core/content/server"; import { CONFIG_PLUGIN } from "@/const"; import { categoryContent } from "@/database/categories"; export const adminModule = buildModule({ pluginId: CONFIG_PLUGIN.pluginId, name: "admin", routes: [], modules: [ buildContentAdminModule({ pluginId: CONFIG_PLUGIN.pluginId, contentTypes: [categoryContent], }), ], }); ``` Then add the module to your API plugin. This is an excerpt of `src/config.api.ts`: ```ts title="plugins/example/src/config.api.ts" import { adminModule } from "@/api/modules/admin/admin.module"; // [!code ++] export const exampleApiPlugin = () => buildApiPlugin({ pluginId: CONFIG_PLUGIN.pluginId, modules: [adminModule], // [!code highlight] }); ``` The routes live under `/api/@vitnode/example/admin/content/category` and only answer staff signed in to the AdminCP. Keep the module named `admin`, because the API checks the AdminCP session on paths that contain `/admin/`. ### Add the AdminCP screen [#add-the-admincp-screen] The AdminCP needs two things from your plugin: a sidebar link and the screen behind it. They live in separate files on purpose. The sidebar loads on every AdminCP page, while the screen's forms load only when someone opens it. Create `src/admin/nav.tsx` with the sidebar link: ```tsx title="plugins/example/src/admin/nav.tsx" import { FolderIcon } from "lucide-react"; import { CONFIG_PLUGIN } from "@/const"; import { categoryContentType } from "@/content/category"; export const adminNav = { pluginId: CONFIG_PLUGIN.pluginId, contentTypes: [{ definition: categoryContentType, icon: }], }; ``` Create `src/admin/content.tsx` and reuse the same list for the screen: ```tsx title="plugins/example/src/admin/content.tsx" export { adminNav as adminContent } from "./nav"; ``` That one line is enough for the generated list and forms. Later, this is the file where you swap in [custom cells, fields or form layouts](/docs/content-engine/admincp). VitNode finds both files by name, so keep the paths and the `adminNav` and `adminContent` exports. ### Name everything [#name-everything] Labels come from your plugin's `src/locales/en.json`. Content type strings live under `content.category`, and each staff permission gets a top-level key: ```json title="plugins/example/src/locales/en.json" { "@vitnode/example": { "title": "Example", "content": { "category": { "label": "{count, plural, one {Category} other {Categories}}", "title": "Categories", "desc": "Group articles together.", "fields": { "name": "Name", "createdAt": "Created" } } } }, "@vitnode/example:category": "Categories", "@vitnode/example:category:can_view": "View categories", "@vitnode/example:category:can_create": "Create categories", "@vitnode/example:category:can_edit": "Edit categories", "@vitnode/example:category:can_delete": "Delete categories" } ``` `label` is an ICU plural, used in buttons and messages such as **Create Category**. `title` and `desc` head the list, and the plugin's own `title` names the sidebar group. A missing key falls back to a readable version of the field name, and a missing permission label shows its raw id. ### Build and migrate [#build-and-migrate] Run this from the workspace root: ```bash tab="bun" bun run build:plugins && bun run db:migrate ``` ```bash tab="pnpm" pnpm build:plugins && pnpm db:migrate ``` ```bash tab="npm" npm run build:plugins && npm run db:migrate ``` `db:migrate` reads the built plugin, so always build first. It writes a migration to `apps/api/migrations/` and applies it. This is the part of the example plugin's migration that creates categories: ```sql title="apps/api/migrations/20260802212938_add_example_content/migration.sql (excerpt)" CREATE TABLE "example_categories" ( "id" serial PRIMARY KEY NOT NULL, "createdAt" timestamp DEFAULT now() NOT NULL, "updatedAt" timestamp DEFAULT now() NOT NULL, "name" varchar(100) NOT NULL ); ALTER TABLE "example_categories" ENABLE ROW LEVEL SECURITY; CREATE INDEX "example_categories_created_at_idx" ON "example_categories" USING btree ("createdAt"); CREATE INDEX "example_categories_updated_at_idx" ON "example_categories" USING btree ("updatedAt"); ``` You declared one field. The engine added `id`, the two timestamps and their indexes. [Database](/docs/content-engine/database) lists everything it generates. ### Restart the dev server [#restart-the-dev-server] Stop `pnpm dev` and start it again. The API registers routes when it starts, so the new staff routes exist only after a restart. ### Create a few categories [#create-a-few-categories] Open **AdminCP → Example → Categories** and click **Create Category**. The dialog is generated from your fields, so it has a single **Name** input with the 1 to 100 character limit from the definition. Click **Create**. A toast says "Category has been created." and the list refreshes. Add a couple more so there is something to sort. ## Check the result [#check-the-result] The list shows your categories with the **Name** and **Created** columns from `list.columns`. Click **Name** to sort, or type in the search box to filter by name. Now open **AdminCP → Staff → Administrators**, edit an administrator, choose **Restricted** and select **Example**. The **Categories** group holds the four permissions the Content Engine generated from your definition, labelled by your locale keys. Create, edit and delete each require view. Every generated route checks them, so an administrator without **Delete categories** gets a `403` from the delete route and no delete button in the list. The `advanced_article`, `localized_article` and `page` groups next to it have no labels in the example plugin. That is what a missing permission key looks like. ## Next [#next] Categories are staff-only. To publish content to visitors, add drafts and a read-only API in [Public API](/docs/content-engine/public-api). # Database (/docs/content-engine/database) Every content type becomes ordinary Postgres tables managed by Drizzle. `createContentModel` from `@vitnode/core/content/server` builds them from the definition, and the usual VitNode migration workflow creates them. Values are stored in typed columns. Only `field.blocks()` and `field.richText()` keep a JSON document, in a `jsonb` column. ## Generate and apply a migration [#generate-and-apply-a-migration] After you add or change a content type, run this from the workspace root: ```bash tab="bun" bun run build:plugins && bun run db:migrate ``` ```bash tab="pnpm" pnpm build:plugins && pnpm db:migrate ``` ```bash tab="npm" npm run build:plugins && npm run db:migrate ``` 1. `build:plugins` compiles each plugin to `dist/`. `db:migrate` reads that output and does not build, so skipping this step migrates the old schema. 2. `db:migrate` compares the exported tables of every plugin in your API config with the last snapshot and writes a new folder to `apps/api/migrations/`. 3. It applies pending migrations, then makes sure the initial data exists. Commit the generated migration together with the content type. Production never migrates on startup, so run migrations as a deploy step. [Database CLI](/docs/dev/cli/database) covers `vitnode db generate --name ` for a named migration, `vitnode db status` and the rest. ## Export every table [#export-every-table] Drizzle Kit finds tables by reading the exports of `node_modules//dist/src/database/*.js` for each plugin. A table without an export is left out of the migration, without a warning. A content type with relations, translations and repeatable rows has several tables: ```ts title="plugins/example/src/database/advanced-articles.ts" import { createContentModel } from "@vitnode/core/content/server"; import { advancedArticleContentType } from "@/content/advanced-article"; import { example_categories } from "./categories"; export const advancedArticleContent = createContentModel( advancedArticleContentType, { references: { categories: () => example_categories.id, }, }, ); export const example_advanced_articles = advancedArticleContent.table; export const example_advanced_articles_translations = advancedArticleContent.translationTable; export const example_advanced_articles_categories = advancedArticleContent.advancedTables.junctions.categories; export const example_advanced_articles_related_articles = advancedArticleContent.advancedTables.junctions.relatedArticles; export const example_advanced_articles_faq = advancedArticleContent.advancedTables.repeatables.faq; ``` | Model member | Exists when | | ------------------------------------ | --------------------------------------------------------- | | `table` | Always | | `translationTable` | `localization` is enabled; otherwise `null` | | `advancedTables.junctions.` | A `relation`, `user` or `file` field has `multiple: true` | | `advancedTables.repeatables.` | The content type has a `field.repeatable()` | `references` maps each `relation` field to the column it points at. `user` and `file` fields need no entry, because the engine knows `core_users` and `core_files`. See [Relations](/docs/content-engine/relations). ## Generated columns [#generated-columns] You never declare these. A field with the same name throws an error. | Column | Type | Added when | | ------------- | ------------------------------------------------------------------------- | ------------- | | `id` | Primary key, typed by [`idStrategy`](#ids-and-shared-tables) | Always | | `createdAt` | `timestamp`, defaults to `now()` | Always | | `updatedAt` | `timestamp`, defaults to `now()`, refreshed by every update | Always | | `status` | `varchar(32)`, `draft` or `published`, defaults to `draft` | `publication` | | `publishedAt` | `timestamp`, nullable | `publication` | | `version` | `integer`, defaults to `1` | `editorial` | | `hiddenAt` | `timestamp`, nullable | `visibility` | | `hiddenBy` | `integer`, nullable, references `core_users.id` with `ON DELETE SET NULL` | `visibility` | Column names are camelCase in SQL, exactly as in TypeScript. Every generated table has row-level security enabled. A field group adds one column per leaf to the main table, so the `syndication` group's `indexable` field becomes `syndicationIndexable`. Column types per field are listed in [Fields](/docs/content-engine/fields). ### Translations table [#translations-table] With `localization`, `{tableName}_translations` holds the localized fields: | Column | Notes | | ------------------------ | ------------------------------------------------------------------------------------------------------- | | `itemId` | References the main table, with the same type as its `id`. Deleting the record deletes its translations | | `languageId` | References `core_languages.id`. A language with content cannot be deleted | | `version` | Per-language version, always present | | `createdAt`, `updatedAt` | Same as the main table | | `status`, `publishedAt` | With `publication`. Each language is published on its own | The primary key is `(itemId, languageId)`, so a record has at most one translation per language. ### Junction and child tables [#junction-and-child-tables] Field names become snake_case in table names, so `relatedArticles` on `example_advanced_articles` becomes `example_advanced_articles_related_articles`. - A **to-many field** gets `{tableName}_{field}` with `itemId`, `relatedItemId`, `position` and `createdAt`. The primary key is `(itemId, relatedItemId)`, so a record links to each target once. - A **repeatable field** gets `{tableName}_{field}` with `id`, `itemId`, `position`, `createdAt`, `updatedAt` and one column per subfield. Deleting a record deletes its junction and repeatable rows. Both kinds keep `position` unique per record. That column holds the order an editor picks in the AdminCP. Every column that points at a record has the type of that record's key. In a junction table, `itemId` follows the owner's `idStrategy` and `relatedItemId` follows the target's. A repeatable's own `id` is always `serial`, while its `itemId` follows the owner. User and file references are always `integer`. ## IDs and shared tables [#ids-and-shared-tables] The [id strategy](/docs/content-engine/id-strategy) sets the key column: | `idStrategy` | `id` column | | -------------------- | ----------------------------------------------------- | | `"serial"` (default) | `serial PRIMARY KEY` | | `"uuid"` | `uuid PRIMARY KEY DEFAULT gen_random_uuid()` | | `"bigint"` | `bigint PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY` | Core tables that hold records of every content type store the id as text: `core_content_revisions`, `core_content_schedules`, `core_content_slug_history`, `core_search_index`, the [live editing](/docs/content-engine/live-editing-api#where-the-data-lives) tables `core_content_drafts`, `core_content_field_locks` and `core_content_documents`, and `core_ai_translation_sources`. Their `itemId` is a `varchar(64)` holding `contentIdKey(id)`: the digits of a serial or bigint id, or the UUID. Migration `20261011093549_content_visibility_id_strategies` converted them in place from `integer`, so existing serial keys keep their digits: ```sql title="apps/api/migrations/20261011093549_content_visibility_id_strategies/migration.sql (excerpt)" ALTER TABLE "core_content_revisions" ALTER COLUMN "itemId" SET DATA TYPE varchar(64) USING "itemId"::varchar(64); ``` Custom SQL that joins these tables to a content table needs a cast, such as `"core_content_revisions"."itemId" = "example_articles"."id"::text`. ## Generated indexes [#generated-indexes] The engine creates these indexes without being asked: - A unique index on every slug, and on every `field.text({ unique: true })`. - An index on every single `relation`, `user` and `file` column, and on `hiddenBy` with `visibility`. - Indexes on `createdAt` and `updatedAt`. - `(status, publishedAt)` with `publication`. - On a translations table: `(languageId, status)` with `publication` or `(languageId)` without it, plus a unique `(languageId, slug)` for each localized slug. - On a junction table: `relatedItemId`, and a unique `(itemId, position)`. On a repeatable table: a unique `(itemId, position)`. Generated names follow `{table}_{columns}_idx`, or `_key` for unique ones, such as `example_categories_created_at_idx`. Add your own with the [`indexes`](/docs/content-engine/reference) option. An index on the same columns as a generated one replaces it instead of adding a second one: ```ts title="plugins/example/src/content/article.ts" indexes: [{ on: ["status", "createdAt"] }], ``` ## Change a content type later [#change-a-content-type-later] Changing a definition is a schema change like any other. Build, migrate and read the generated SQL before you commit it. - **Adding a nullable field, or one with a `defaultValue`,** is safe on a table that already has rows. - **Adding a required field without a default** fails on a table with rows. Add it as nullable, fill it, then make it required in a second migration. - **Renaming a field** renames its column. Check that the generated SQL says `RENAME COLUMN`, not a drop followed by an add, or the old values are lost. - **Turning on `localization`** moves localized fields to a new translations table. The generated SQL does not copy existing values, so add the data move to the migration yourself. - **Turning on `visibility`** adds two nullable columns, so existing records stay visible. - **Changing `idStrategy`** on a table with data is not something the generated SQL can do. It needs a hand-written data migration that converts the key, every column that references it and the keys in the shared tables. See [Change the strategy later](/docs/content-engine/id-strategy#change-the-strategy-later). - **Never edit or regenerate a migration that has already been applied.** Write a new one instead. # Duplicate content (/docs/content-engine/duplicate-content) Duplication copies one record into a new draft: every field, every translation, relations in their order and repeatable rows. The blog uses it so an editor can start a new article from a similar one, or prepare a rewrite of a published article without touching the live version. ### Turn on duplication [#turn-on-duplication] Add `duplication: true` to the definition. The blog's article content type does exactly that: ```ts title="plugins/blog/src/content/post.ts" export const blogPostContentType = defineContentType({ id: "blog.post", tableName: "blog_posts", publication: true, duplication: true, // [!code ++] // ... }); ``` Duplication adds no column, so there is nothing to migrate, and no new permission. Duplicating needs `can_create` and `can_view`, because it creates a record by reading another. For the blog those are **Create articles** and **View articles list**. Run `pnpm build:plugins` and restart `pnpm dev`. ### Duplicate an article in the AdminCP [#duplicate-an-article-in-the-admincp] Open **AdminCP → Blog → Articles**, open the **More actions** menu of an article and choose **Duplicate**. Confirm with **Yes, duplicate it**: The list refreshes, a toast says the article was duplicated as a draft, and the copy opens on its edit page (or in the edit dialog, for a content type whose `admin.edit.mode` is `"dialog"`). If some of the source's languages are switched off on this site, a second toast lists the ones that were left out. Duplicating the blog's "Hello world", published in English and Polish with its categories and authors, creates a draft with: | Language | Title | Slug | | -------- | -------------------- | -------------------- | | English | Hello world (Copy) | `hello-world-copy` | | Polish | Witaj świecie (Copy) | `witaj-swiecie-copy` | The copy has the same categories and the same authors in the same order, and each language starts its own revision history. ## What the copy contains [#what-the-copy-contains] | Copied | Not copied | | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Every declared field, including rich text, groups and blocks | Revisions, schedules and preview links | | Repeatable rows, as new rows in the same order | Slug history and redirects | | Relation, user and file references, in their order. Files are reused, not uploaded again | Published state and `publishedAt`: the copy is a draft | | Every translation, each as a draft with its own first revision | Hidden state: the copy is never [hidden](/docs/content-engine/content-visibility) | The copy gets a new id, new timestamps and `version` 1. Everything happens in one database transaction, so a failure leaves nothing behind. The source is only read, so its history gets no new revision. ### Titles and slugs [#titles-and-slugs] When `admin.titleField` is a `field.text()`, the copy's title gets a suffix in each language, such as "Hello world (Copy)". The source title is shortened when the suffix would push it past the field's `maxLength`. The suffix is the core API message `core.content.duplicate.title_suffix`, resolved in each copied language and falling back to "(Copy)". Turn the suffix off with `duplication: { titleSuffix: false }`. `titleSuffix: true` with a title field that is not a text field throws when the content type is defined. Each slug is regenerated from the copy's title, so `hello-world` becomes `hello-world-copy`. A slug without a `source` gets `-copy` appended. When that slug is taken, by a live record or by another record's old URL, the engine tries `-2`, `-3` and so on, up to 20 candidates. ### Unique fields [#unique-fields] A `field.text({ unique: true })` cannot keep the source's value. Duplicating such a record without a new value fails before anything is written, with `422` and the code `CONTENT_DUPLICATE_UNIQUE_REQUIRED`. Pass the new value as an override from the API, as shown below. ## Duplicate from the API [#duplicate-from-the-api] The admin module of a content type with duplication has `POST /{id}/duplicate`. For the blog, the module is named after its permission module, `posts`: ```http POST /api/@vitnode/blog/admin/content/posts/701/duplicate Content-Type: application/json { "translations": { "en": { "title": "Hello again", "friendlyUrl": "hello-again" }, "pl": { "title": "Witaj ponownie" } } } ``` The body is optional: | Name | Type | Description | | -------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `overrides` | Partial shared field values | Values the copy takes instead of the source's. A group is merged leaf by leaf. Validated like a create | | `translations` | `{ [locale]: partial localized values }` | Localized values per copied language. A language the source has no translation in is a `400` | A slug you pass is used as it is, without `-copy`, and a title you pass is used without the "(Copy)" suffix. In the example above, the English copy is "Hello again" at `hello-again`, and the Polish copy is "Witaj ponownie" with the slug `witaj-ponownie` generated from that title. The response is `201` with `{ id, sourceId, row, locales, skippedLocales }`: the copy's id, the source id, the new row, the copied languages and the languages left out because they are switched off. | Status | When | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | An invalid id, override or translation | | `403` | Missing `can_create` or `can_view` | | `404` | The source does not exist | | `409` | No free slug was found (`CONTENT_DUPLICATE_SLUG_CONFLICT`, with `field`, `locale` and `slug`), or an override collides with another record | | `422` | A unique field needs an override (`CONTENT_DUPLICATE_UNIQUE_REQUIRED`, with `fields`) | ## Duplicate from your own code [#duplicate-from-your-own-code] `service(c).duplicate(sourceId, options)` and `editorialService(c, { pluginId }).duplicate(sourceId, { actor, ...options })` take the same `overrides` and `translations`, plus `tx`. Both exist only when duplication is on, and both return `null` when the source does not exist. The services do not emit events or index the copy. Run `contentDuplicateEffects` from `@vitnode/core/content/server` after the transaction commits, as the generated route does: ```ts import { contentDuplicateEffects, resolveContentActor } from "@vitnode/core/content/server"; const { editorialService } = postContent; if (!editorialService) throw new Error("Articles have no editorial features."); const pluginId = CONFIG_PLUGIN.pluginId; const actor = resolveContentActor(c); const outcome = await editorialService(c, { pluginId }).duplicate(sourceId, { actor, }); if (outcome) { await contentDuplicateEffects( c, postContent, { kind: "editorial", outcome }, { actorUserId: actor.userId, pluginId }, ); } ``` The effects emit `content.blog.post.created` with `duplicatedFromId`, one `translation_created` per copied language, and then `content.blog.post.duplicated`. They also add the copy to the search index as a private draft. See [Events](/docs/content-engine/events). ## Check the result [#check-the-result] Duplicate "Hello world" and go back to the list. "Hello world (Copy)" is a **Draft**, and `/blog/hello-world-copy` answers `404` until you publish it. Open the original's **History** and you'll find no new revision. As far as the original knows, nothing happened. # Editorial (/docs/content-engine/editorial) The `editorial` block gives a content type the tools an editorial team expects: a history of every save with restore, protection against two people overwriting each other, signed links that show a draft to someone without an AdminCP account, and publishing at a chosen time. It is also what [live editing](/docs/content-engine/live-editing) builds on, which you turn on separately with `liveEditing: true`. This page uses `example.article` from the example plugin. It already has [drafts and publishing](/docs/content-engine/public-api) and a public API, which previews and scheduling build on. ## Turn on editorial features [#turn-on-editorial-features] Add `editorial` to the definition: ```ts title="plugins/example/src/content/article.ts" export const articleContentType = defineContentType({ id: "example.article", tableName: "example_articles", publication: true, publicApi: { path: "articles", fields: ["title", "slug", "excerpt"], }, // [!code ++:5] editorial: { revisions: { retention: 20 }, preview: { expiresInMinutes: 30 }, scheduling: true, }, fields: { title: field.text({ required: true, minLength: 3, maxLength: 200 }), slug: field.slug({ source: "title" }), }, }); ``` Then rebuild the plugin and migrate: ```bash tab="bun" bun run build:plugins && bun run db:migrate ``` ```bash tab="pnpm" pnpm build:plugins && pnpm db:migrate ``` ```bash tab="npm" npm run build:plugins && npm run db:migrate ``` The migration adds a `version` column to `example_articles`. Revisions, schedules, drafts and locks live in shared core tables, so nothing else lands in your schema. Editorial also adds a `can_restore` staff permission, labelled by the `@vitnode/example:article:can_restore` key in your plugin's locale file. `preview` needs `publicApi` and `scheduling` needs `publication`. Leaving out the partner is a type error, and the definition throws when it loads. Every option and default is in the [content type reference](/docs/content-engine/reference#editorial). ## Revisions [#revisions] Every create, update, publish, unpublish and restore stores a snapshot in `core_content_revisions`, and so does every hide and unhide with [`visibility`](/docs/content-engine/content-visibility). `revisions.retention` keeps the newest snapshots per record, 50 by default and at most 500. To see them, open the row's **More actions** menu in the AdminCP list and choose **History**. Each version shows who saved it and when, and **Show changes** lists the fields it changed: **Restore** puts that version's field values back as a new version, so nothing in between is lost. The publication status and the [hidden](/docs/content-engine/content-visibility) state stay as they are. It needs `can_restore` and emits `content.example.article.restored`. Anyone with the record open in [live editing](/docs/content-engine/live-editing) gets a notice and a reloaded form. ## Safe concurrent edits [#safe-concurrent-edits] Each editorial write raises the record's `version` by one and succeeds only when the version still matches the one the editor loaded. If someone saved in between, the second save fails instead of quietly replacing their work: ```json title="PUT /api/@vitnode/example/admin/content/article/2 → 409" { "code": "CONTENT_VERSION_CONFLICT", "contentTypeId": "example.article", "itemId": 2, "expectedVersion": 2, "currentVersion": 3 } ``` The AdminCP sends the version for you. Your own calls to the edit routes must send it too: `PUT /{id}` takes `{ "expectedVersion": 3, "values": { "title": "…" } }` and `DELETE /{id}` takes `{ "expectedVersion": 3 }`. In server code, `articleContent.editorialService` does the same check; see the [Feature this article example](/docs/content-engine/services#example-3-a-feature-this-article-button). A translation has its own version and fails with `CONTENT_TRANSLATION_VERSION_CONFLICT`. ## Preview links [#preview-links] A preview link lets a reviewer read a draft without signing in. In the AdminCP, open **More actions** and choose **Preview**. Creating a link needs `can_view`. The link is HMAC-signed, expires after `expiresInMinutes` (15 by default, 1 to 1440) and cannot be revoked early, so treat it like a password. It is pinned to the last saved version, so it shows what **Save** committed, not unsaved [live editing](/docs/content-engine/live-editing) drafts. The link points to the first of these that exists: 1. `preview.pathTemplate`, such as `/preview/articles/{token}`, with exactly one `{token}`. 2. The record's own page with `?preview=`, when the type has [delivery](/docs/content-engine/public-pages). 3. The public API route `GET /api/@vitnode/example/content/articles/preview/{token}`. Every page still has to load the draft from that API route. A page built from [Show content on a public page](/docs/content-engine/public-pages) does not read `?preview=` on its own, so the example's link opens a 404 until you check for it in your loader: ```ts title="Read a preview in a page loader" const preview = await fetcher({ plugin: "@vitnode/example", method: "get", module: "content/articles", path: "/preview/{token}", args: { params: { token: encodeURIComponent(token) } }, }); ``` The route returns the record's public fields, and the same `404` for a forged, expired or unknown token. It sends `Cache-Control: private, no-store` and `X-Robots-Tag: noindex, nofollow`, so the draft stays out of caches and search results. Links are built from `VITNODE_WEB_URL` and `VITNODE_API_URL`. When either is not an absolute URL, the API logs a warning at startup and the **Preview** button answers `503`. ## Schedule publishing [#schedule-publishing] Scheduling publishes or unpublishes a record at a chosen time. Open **More actions**, choose **Schedule**, pick **Publish** or **Unpublish** and a time, then press **Schedule it**. Booking or cancelling a schedule needs `can_publish`. A schedule is a queued task, drained by the `process-queue` [cron job](/docs/dev/cron) once a minute. If nothing triggers your cron endpoint, schedules are saved but never fire. When the install has no cron adapter at all, the dialog says so with a **No scheduler is running** warning. When a schedule fires, it publishes whatever the record says at that moment, not what it said when you booked it. A few rules keep schedules sane: - A time up to two minutes in the past is accepted. Anything older fails with `CONTENT_SCHEDULE_IN_PAST`. - An unpublish cannot come before a pending publish (`CONTENT_SCHEDULE_ORDER`). - Booking emits `content.example.article.scheduled` and cancelling emits `schedule_cancelled`. When the time comes, the usual `published` or `unpublished` event carries the `scheduleId`. - A scheduled publish of a [hidden](/docs/content-engine/content-visibility) record leaves it hidden, so it stays off the public site until someone unhides it. If a separate front end caches pages, [Notify a separate front end](/docs/content-engine/caching#notify-a-separate-front-end) tells it about the change. # Events (/docs/content-engine/events) Each content type emits events named `content..` after a change, such as `content.example.article.published`. Subscribe to them to send a newsletter, sync an external index or purge a CDN, without touching the code that made the change. Events come from the generated routes, scheduled publishing and [`contentEditorialEffects`](/docs/content-engine/services#example-3-a-feature-this-article-button). The plain `service(c)` emits nothing. A save that changes nothing emits nothing either. ## Event reference [#event-reference] Which events exist depends on what the definition enables. `example.category` declares only fields and emits three; `example.article` has publication, editorial with scheduling and delivery, and emits ten. | Action | Payload | Needs | | --------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------ | | `created` | `{ contentId, duplicatedFromId? }` | always | | `updated` | `{ contentId, changedFields }` | always | | `deleted` | `{ contentId }` | always | | `published` | `{ contentId, publishedAt, scheduledBy?, scheduleId? }` | `publication` | | `unpublished` | `{ contentId, scheduledBy?, scheduleId? }` | `publication` | | `restored` | `{ contentId, changedFields, version, revisionId, restoredFromRevisionId }` | `editorial` | | `scheduled` | `{ contentId, action, actorUserId, scheduledFor, scheduleId }` | `editorial.scheduling` | | `schedule_cancelled` | `{ contentId, action, actorUserId, scheduleId }` | `editorial.scheduling` | | `translation_created` | `{ contentId, locale, languageId, version, revisionId? }` | `localization` | | `translation_updated` | `{ contentId, locale, languageId, version, changedFields, revisionId? }` | `localization` | | `translation_deleted` | `{ contentId, locale, languageId, version, revisionId? }` | `localization` | | `translation_published` | `{ contentId, locale, languageId, version, publishedAt, revisionId? }` | `localization` + `publication` | | `translation_unpublished` | `{ contentId, locale, languageId, version, revisionId? }` | `localization` + `publication` | | `translation_restored` | `{ contentId, locale, languageId, version, changedFields, revisionId, restoredFromRevisionId }` | `localization` + `editorial` | | `delivery_slug_changed` | `{ contentId, slug, previousSlug, previousPath, canonicalPath, locale }` | `delivery` | | `delivery_redirect_created` | `{ contentId, previousSlug, previousPath, canonicalPath, locale }` | `delivery` | | `duplicated` | `{ actorUserId, contentId, contentTypeId, sourceId }` | `duplication` | | `hidden` | `{ actorUserId, contentId, hiddenAt }` | `visibility` | | `unhidden` | `{ actorUserId, contentId }` | `visibility` | A few payload details that change what a listener does: - `contentId` has the type of the content type's [id strategy](/docs/content-engine/id-strategy): a `number` for `serial`, a `string` for `uuid` and `bigint`. A bigint id arrives as its exact decimal string. - A [duplicate](/docs/content-engine/duplicate-content) emits the copy's `created` with `duplicatedFromId`, one `translation_created` per copied language, then `duplicated`. `duplicatedFromId` is absent on an ordinary create. - `hidden` and `unhidden` never replace `published` or `unpublished`, because [hiding](/docs/content-engine/content-visibility) does not change the status. - `changedFields` lists only the fields whose value actually moved, typed as the content type's own field names. On translation events it names localized fields only. - `restored` replaces `updated` for a rollback, so a listener that cares about field changes should handle both. - `publishedAt` is when the record first went live. It is never rewritten, and it can be missing, so guard for `undefined`. - `scheduledBy` and `scheduleId` are set only when a schedule fired the change. `actorUserId` on `scheduled` is the same person as `scheduledBy` later. - The delivery events arrive alongside `updated`, `restored` or a publication event, never instead of them. `locale` is `null` for a shared slug. [Container collections](/docs/content-engine/containers) emit their own four events, `content.container.created`, `updated`, `moved` and `deleted`, listed in [Container hierarchy](/docs/content-engine/container-hierarchy#events). The listener also receives an envelope with the actor, the time and `pluginId`. `pluginId` is always the plugin that owns the content type, even when a core queue task ran the change. Field-by-field descriptions are in [Built-in events](/docs/dev/events/built-in-events#content-engine-events). ## Subscribe to an event [#subscribe-to-an-event] ### Register the event types [#register-the-event-types] Add the content type to the global event map once per plugin. The listener's event name and payload are then type-checked, and an event the definition does not enable, such as `content.example.category.published`, does not compile. ```ts title="plugins/example/src/api/lib/events.ts" import type { ContentEventsFor } from "@vitnode/core/content"; import type { articleContentType } from "@/content/article"; import type { categoryContentType } from "@/content/category"; declare module "@vitnode/core/api/models/events" { interface VitNodeEvents extends ContentEventsFor, ContentEventsFor {} } ``` The example plugin imports this file from `config.api.ts` with `import "@/api/lib/events";`, so the declaration travels with the API build. ### Write the listener [#write-the-listener] `contentEventName(id, action)` builds the name from the definition, so a renamed content type cannot leave a stale string behind: ```ts title="plugins/example/src/api/lib/listeners.ts" import { buildEventListener } from "@vitnode/core/api/lib/events"; import { contentEventName } from "@vitnode/core/content"; import { articleContentType } from "@/content/article"; export const announceArticleListener = buildEventListener({ event: contentEventName(articleContentType.id, "published"), name: "announce-published-article", description: "Logs every article that goes live", handler: async (c, payload) => { await c.get("log").debug(`Article ${payload.contentId} was published`); }, }); ``` ### Add it to a top-level module [#add-it-to-a-top-level-module] VitNode collects listeners only from the `events` array of a module passed directly to `buildApiPlugin`. A listener on a nested module is silently ignored. ```ts title="plugins/example/src/api/modules/admin/admin.module.ts" export const adminModule = buildModule({ pluginId: CONFIG_PLUGIN.pluginId, name: "admin", routes: [], modules: [ buildContentAdminModule({ pluginId: CONFIG_PLUGIN.pluginId, contentTypes: [articleContent], }), ], events: [announceArticleListener], // [!code ++] }); ``` The blog plugin does the same with its `blogLegacyEventListeners`, which turn `content.blog.post.created` into the older `blog.post.created` event. ## Check the result [#check-the-result] Restart `pnpm dev`, publish an article in **AdminCP → Example → Articles** and look for the debug line in the API terminal. A failing listener does not undo the change. The write has already committed, and the engine logs the failure. Events from a scheduled publish run in a queue task that retries on failure, so the same `published` event can arrive twice. Make work that must happen once idempotent, for example keyed on `scheduleId`. See [A scheduled event may arrive twice](/docs/dev/events/built-in-events#a-scheduled-event-may-arrive-twice). # Fields (/docs/content-engine/fields) A field is one property of a content type, such as a title or a view count. You build each one with a helper from `field`, exported by `@vitnode/core/content`. The helper decides three things at once: the Postgres column, the validation of every write and the control in the AdminCP form. ```ts title="plugins/example/src/content/article.ts" import { defineContentType, field } from "@vitnode/core/content"; export const articleContentType = defineContentType({ id: "example.article", tableName: "example_articles", fields: { title: field.text({ required: true, minLength: 3, maxLength: 200 }), slug: field.slug({ source: "title" }), views: field.number({ integer: true, min: 0, defaultValue: 0 }), featured: field.boolean({ defaultValue: false }), author: field.user(), }, }); ``` The example plugin's article form shows most controls. The first half holds the plain values: The second half holds the references: a user picker, two file dropzones and a relation picker. ## Field helpers [#field-helpers] | Helper | Postgres column | AdminCP control | Can be `localized` | | -------------------- | -------------------------------------------------- | ---------------------------------------- | ------------------ | | `field.text()` | `varchar(maxLength)`, 255 by default | Text input | Yes | | `field.textarea()` | `text` | Textarea | Yes | | `field.richText()` | `jsonb` | Rich text editor | Yes | | `field.number()` | `integer` or `double precision` | Number input with steppers | No | | `field.boolean()` | `boolean` | Switch | No | | `field.enum()` | `varchar(length)`, 64 by default | Select or radio buttons | No | | `field.dateTime()` | `timestamp` | Date and time picker | No | | `field.slug()` | `varchar(maxLength)`, 160 by default, unique | Text input | Yes | | `field.user()` | `integer` referencing `core_users.id` | User picker | No | | `field.file()` | `integer` referencing `core_files.id` | File dropzone | No | | `field.relation()` | The target's key type, referencing its table | Search picker | No | | `field.container()` | `integer` referencing `core_content_containers.id` | Container tree picker | No | | `field.group()` | One column per leaf | A fieldset with the leaf controls | Yes, as a whole | | `field.repeatable()` | A child table | A list of rows you can add, move, remove | No | | `field.blocks()` | `jsonb`, `NOT NULL DEFAULT '[]'` | Not in the form; edited as widgets | Yes | `user`, `file` and `relation` with `multiple: true` store their values in a junction table instead of a column. Localized fields live in the translation table. See [Translations](/docs/content-engine/localization). ## Shared options [#shared-options] Every helper except `slug`, `repeatable` and `blocks` accepts these: | Name | Type | Required | Default | Description | | ------------- | --------- | -------- | ------- | ---------------------------------------------------------- | | `required` | `boolean` | No | `false` | A create request must include the field | | `nullable` | `boolean` | No | `false` | The column accepts `NULL`, and so does validation | | `description` | `string` | No | | Text or an i18n key shown under the control in the AdminCP | A field that is neither required nor nullable needs a fallback, or `defineContentType` throws `Field "x" is neither required nor nullable, so it needs a default value`. A `defaultValue`, `defaultNow: true` on a date and `source` on a slug all count as a fallback. On update every field is optional. `required: true` on a text field still accepts an empty string. Add `minLength: 1` when you need actual text. ## Text and textarea [#text-and-textarea] ```ts code: field.text({ required: true, maxLength: 100, unique: true }), excerpt: field.textarea({ maxLength: 500, nullable: true }), ``` | Name | Type | Required | Default | Description | | -------------- | --------- | -------- | -------------------- | ------------------------------------------------------------------------ | | `minLength` | `number` | No | | Shortest accepted value, in characters | | `maxLength` | `number` | No | 255 column on `text` | Longest accepted value. On `text` it is also the `varchar` length | | `defaultValue` | `string` | No | | Written when a create leaves the field out. Becomes the column `DEFAULT` | | `unique` | `boolean` | No | `false` | `text` only. Adds a unique index. Has no effect on a localized field | | `localized` | `boolean` | No | `false` | One value per language | | `ai` | object | No | | Adds an AI suggestion button, see [AI suggestions](#ai-suggestions) | Set `maxLength` on every `text` field. Without it, validation accepts any length, and Postgres rejects anything over 255 characters with a database error instead of a validation message. A `defaultValue` must satisfy the field's own `minLength` and `maxLength`. ## Rich text [#rich-text] ```ts content: field.richText({ localized: true, required: true }), ``` | Name | Type | Required | Default | Description | | ----------- | --------- | -------- | ------- | ------------------------------------------------------- | | `maxBytes` | `number` | No | 1 MB | Largest document, measured as UTF-8 JSON. At most 16 MB | | `localized` | `boolean` | No | `false` | One document per language | The value is a ProseMirror JSON document. A rich text field has no `defaultValue`, so set `required` or `nullable`. With `required: true` a document without any text or media is refused. Documents nested deeper than 64 levels are refused too. [Rich text](/docs/content-engine/rich-text) covers rendering and the plain text and HTML helpers. ## Number [#number] ```ts views: field.number({ integer: true, min: 0, defaultValue: 0 }), ``` | Name | Type | Required | Default | Description | | -------------- | --------- | -------- | ------- | ------------------------------------------------------------------------- | | `integer` | `boolean` | Yes | | `true` makes an `integer` column, `false` a `double precision` one | | `min`, `max` | `number` | No | | Accepted range. With `integer: true` a whole number must fit between them | | `defaultValue` | `number` | No | | Must sit inside the range, and be whole when `integer: true` | ## Boolean [#boolean] ```ts featured: field.boolean({ defaultValue: false }), ``` The only option besides the shared ones is `defaultValue`. A nullable boolean, such as `noIndex: field.boolean({ nullable: true })`, can hold `true`, `false` or `null`. ## Enum [#enum] ```ts difficulty: field.enum({ values: ["easy", "medium", "hard"], defaultValue: "easy", display: "radio" }), ``` | Name | Type | Required | Default | Description | | -------------- | ----------------------- | -------- | ---------- | -------------------------------------- | | `values` | `string[]` | Yes | | Non-empty, without duplicates | | `defaultValue` | one of `values` | No | | | | `display` | `"select"` \| `"radio"` | No | `"select"` | AdminCP control | | `length` | `number` | No | `64` | `varchar` length. Every value must fit | The column is a plain `varchar`, not a Postgres enum, so adding a value later needs no type migration. The AdminCP translates each value from `{pluginId}.content.{entity}.enums.{field}.{value}` when that key exists. ## Date and time [#date-and-time] ```ts eventDate: field.dateTime({ defaultNow: true }), ``` | Name | Type | Required | Default | Description | | ------------ | --------- | -------- | ------- | ------------------------------------------------ | | `defaultNow` | `boolean` | No | `false` | Fills the column with the current time on insert | There is no `defaultValue`. Send dates as ISO 8601 strings. ## Slug [#slug] ```ts slug: field.slug({ source: "title" }), ``` | Name | Type | Required | Default | Description | | ------------- | -------------------- | -------- | ------- | ---------------------------------------------------------- | | `source` | name of a text field | No | | Fills the slug from that field when a create sends no slug | | `maxLength` | `number` | No | `160` | `varchar` length and the point where long slugs are cut | | `localized` | `boolean` | No | `false` | One slug per language | | `description` | `string` | No | | Shown under the input | A slug has no `required` or `nullable` option. It is required when there is no `source`, and it is never empty. Every value is normalized, so `"Weekend Pancakes!"` becomes `weekend-pancakes`. Slugs are unique across the table, or within each language when localized. The slug is derived only on create, so renaming the title later keeps the old URL. `source` must name a `field.text()`, and a localized slug needs a localized source. ## User [#user] ```ts author: field.user(), authorId: field.user({ multiple: true, ordered: true, min: 1 }), ``` | Name | Type | Required | Default | Description | | ---------- | ------------------------------------------- | -------- | --------- | ------------------------------------------ | | `multiple` | `boolean` | No | `false` | Several people, stored in a junction table | | `ordered` | `boolean` | No | `false` | Keeps the order editors arrange | | `min` | `number` | No | | Fewest people. Needs `multiple` | | `onDelete` | `"cascade"` \| `"restrict"` \| `"set null"` | No | see below | What deleting the user does | A single user field is nullable unless you set `required: true`. `onDelete` defaults to `"set null"` for a nullable single user, `"restrict"` for a required one and `"cascade"` for `multiple`. User fields cannot be listed in `publicApi.fields`. ## File [#file] ```ts animation: field.file({ maxBytes: 10 * 1024 * 1024, allowedExtensions: [".gif"], allowedMimeTypes: ["image/gif"], }), gallery: field.file({ multiple: true, min: 1, max: 8, maxBytes: 5 * 1024 * 1024 }), ``` | Name | Type | Required | Default | Description | | ------------------- | ---------- | -------- | ------------------ | ------------------------------------------ | | `maxBytes` | `number` | Yes | | Largest accepted file, in bytes | | `allowedExtensions` | `string[]` | No | any | Lowercased, with a leading dot added | | `allowedMimeTypes` | `string[]` | No | any | Lowercased | | `multiple` | `boolean` | No | `false` | Several files in a junction table | | `min` | `number` | No | | Fewest files, at least 1. Needs `multiple` | | `max` | `number` | No | `20` | Most files, up to 200. Needs `multiple` | | `ordered` | `boolean` | No | same as `multiple` | Keeps the order editors arrange | A single file field is nullable unless you set `required: true`, and it cannot have a default or be localized. Translate a caption or alt text in a separate localized text field instead. Uploads go through the [storage](/docs/dev/storage) adapter and land in `core_files`. A file in use cannot be deleted, because the reference is `ON DELETE RESTRICT`. The public API returns a file as `{ id, name, url, mimeType, size, width, height }`, never as a raw id. A write may only point at a file uploaded for this content type, uploaded by the signed-in user, or already on the record. The API refuses anything else with `CONTENT_FILE_NOT_FOUND`. ## Relation [#relation] ```ts category: field.relation({ required: true, onDelete: "restrict", target: () => categoryContentType }), ``` | Name | Type | Required | Default | Description | | ---------- | ------------------------------------------- | ------------------ | ------------ | ---------------------------------------------------------------------------- | | `target` | `() => ContentTypeDefinition` | Yes, unless `self` | | The linked content type | | `self` | `true` | No | `false` | Links to the same content type. Do not combine with `target` | | `multiple` | `boolean` | No | `false` | Uses a junction table, up to 500 targets per record | | `ordered` | `boolean` | No | `false` | Keeps the editor's order. Needs `multiple` | | `min` | `number` | No | | Fewest targets, 1 to 500. Needs `multiple` | | `onDelete` | `"restrict"` \| `"cascade"` \| `"set null"` | No | `"restrict"` | What deleting the target does. `"set null"` needs a nullable single relation | A single relation must be `required` or `nullable`. A to-many relation can be neither. The column has the type of the target's key: `integer`, `uuid` or `bigint`, depending on its [`idStrategy`](/docs/content-engine/id-strategy). [Relations](/docs/content-engine/relations) shows the model wiring and the junction tables. ## Container [#container] ```ts board: field.container({ definition: boardContainers, required: true }), ``` | Name | Type | Required | Default | Description | | ------------- | --------------------------------- | -------- | ------- | ------------------------------------------------------------------ | | `definition` | `defineContentContainer()` result | Yes | | The collection the record's container comes from | | `required` | `boolean` | No | `false` | Every record needs a container. Without it, a record may have none | | `description` | `string` | No | | Text or an i18n key shown under the picker in the AdminCP | `field.container()` files a record into one container of a [container collection](/docs/content-engine/containers), such as a discussion into a forum board. `nullable` is always the opposite of `required`, so there is no `nullable` option, no default and no `localized`. A content type can have at most one container field, and its collection must be registered with `buildContentAdminModule({ containers })`. The column is an `ON DELETE RESTRICT` foreign key with an index on the field (plus `publishedAt` when `publication` is on), so a container that still holds records cannot be deleted. Every write checks that the id belongs to the field's collection and answers `400` with `CONTAINER_NOT_FOUND` or `CONTAINER_DEFINITION_MISMATCH` otherwise. The public API returns the container as its id. In `publicApi.filterableFields`, it filters a list with `?board=4`, and `includeDescendants=true` widens that to the whole subtree. In `publicWrite`, it may be listed in `create.fields` but not in `update.fields`. [Containers on the frontend](/docs/content-engine/container-frontend) shows both. ## Group [#group] ```ts syndication: field.group({ fields: { noIndex: field.boolean({ defaultValue: false }), priority: field.number({ integer: true, min: 0, max: 10, defaultValue: 5 }), }, }), ``` | Name | Type | Required | Default | Description | | ----------- | --------------------- | -------- | ------- | -------------------------------------------------------------------- | | `fields` | object of leaf fields | Yes | | `text`, `textarea`, `number`, `boolean`, `enum` or `dateTime` leaves | | `localized` | `boolean` | No | `false` | Moves every leaf to the translation table together | Each leaf becomes a column named ``, such as `syndicationPriority`. Leaves cannot set `localized` themselves. An optional group needs leaves that are nullable or have a default. A nullable group needs nullable leaves. ## Repeatable [#repeatable] ```ts faq: field.repeatable({ max: 20, fields: { question: field.text({ required: true, minLength: 3, maxLength: 200 }), answer: field.textarea({ required: true }), }, }), ``` | Name | Type | Required | Default | Description | | ------------- | --------------------- | -------- | ------- | -------------------------- | | `fields` | object of leaf fields | Yes | | Same leaf kinds as a group | | `min` | `number` | No | `0` | Fewest rows | | `max` | `number` | No | `100` | Most rows, up to 1000 | | `description` | `string` | No | | Shown in the AdminCP form | Rows live in a child table. A repeatable is always shared between languages. ## Blocks [#blocks] ```ts content: field.blocks({ allowed: ["core:*", "example:callout", "example:features"], max: 50 }), ``` | Name | Type | Required | Default | Description | | ------------- | ------------------- | -------- | ------- | ---------------------------------------------- | | `allowed` | `"*"` or `string[]` | No | `"*"` | Which blocks may be placed, such as `"core:*"` | | `min` | `number` | No | | Fewest block instances | | `max` | `number` | No | `200` | Most block instances, up to 1000 | | `localized` | `boolean` | No | `false` | Each language gets its own blocks | | `description` | `string` | No | | | `field.widgets()` is the same helper under another name. A blocks field is never required or nullable. No blocks means an empty list. It does not appear in the AdminCP form. Editors place widgets on the page itself, as described in [The blocks() field](/docs/dev/widgets/blocks-field). ## AI suggestions [#ai-suggestions] `text` and `textarea` fields accept an `ai` option. The form then shows an **AI** button next to the label, like the excerpt in the screenshot above. ```ts excerpt: field.textarea({ ai: { action: "@vitnode/example:article.excerpt", mode: "suggestion", sourceFields: ["title", "code"], }, maxLength: 500, nullable: true, }), ``` | Name | Type | Required | Default | Description | | -------------- | ------------------------- | -------- | ------- | ---------------------------------------------------------------------- | | `action` | `":"` | Yes | | A registered AI action | | `mode` | `"suggestion"` | Yes | | The only supported mode. The editor reviews the text before it is used | | `sourceFields` | `string[]` | Yes | | Other fields of this content type sent to the action as input | [AI in fields and the editor](/docs/dev/ai/fields-and-editor) shows how to write the action. ## Searching and sorting [#searching-and-sorting] Fields have no `searchable` or `sortable` option. Each surface picks its own fields: `admin.list.searchableFields` and `orderableFields` for the AdminCP list, `publicApi.searchableFields`, `orderableFields` and `filterableFields` for the public API, and `search.contentFields` for site search. The [content type reference](/docs/content-engine/reference) lists which field kinds each one accepts. # Record ID strategies (/docs/content-engine/id-strategy) `idStrategy` decides the type of a content type's primary key. The default, `"serial"`, is an auto-incrementing integer. `"uuid"` gives random ids that reveal nothing about how many records exist. `"bigint"` gives integers that will not run out. Pick it when you create the content type, because changing it later means a [hand-written data migration](#change-the-strategy-later), and nobody enjoys those. The example plugin keys its tags by UUID: ```ts title="plugins/example/src/content/tag.ts" export const tagContentType = defineContentType({ id: "example.tag", tableName: "example_tags", idStrategy: "uuid", // [!code ++] localization: { defaultLocale: "en", fallback: "default" }, publication: true, fields: { name: field.text({ localized: true, required: true, minLength: 1, maxLength: 100 }), slug: field.slug({ localized: true, source: "name" }), // category and relatedTags relations }, // editorial, visibility, duplication, publicApi and admin }); ``` ## Strategies [#strategies] | Strategy | Postgres key | In JSON and URLs | In TypeScript | | -------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------- | | `"serial"` (default) | `serial`, up to 2,147,483,647 | A number: `42` | `number` | | `"uuid"` | `uuid`, `DEFAULT gen_random_uuid()` | A lowercase string: `"047d2c6c-1d86-47e2-bcd3-2df9f5359541"` | `string` | | `"bigint"` | `bigint GENERATED BY DEFAULT AS IDENTITY`, up to 9,223,372,036,854,775,807 | A decimal string: `"9007199254740994"` | `string` | Choose by what the ids are for: - **`serial`** suits most content. Ids are short and readable in URLs and logs. The blog's articles and categories use it. - **`uuid`** suits content whose ids should not be guessable or countable, or records created in several places that must not collide. The example plugin's `example.tag` uses it. - **`bigint`** suits tables that may outgrow two billion rows, such as events or logs. The example plugin's `example.event` uses it. Both example types appear in **AdminCP → Example → Tags** and **Events**, and their edit links carry the UUID or the decimal string, such as `/admin/content/example/event/9007199254740994/edit`. ### Why bigint ids are strings [#why-bigint-ids-are-strings] A JavaScript number holds integers exactly only up to 2^53 − 1 (`9007199254740991`). A bigint key can be much larger, and a larger id read as a number is silently rounded to a different record: `Number("9007199254740993")` is `9007199254740992`. VitNode never converts a bigint id through `Number`. Drizzle reads the column in `string` mode, and every API, event, cursor and AdminCP URL carries the exact decimal string. Once the `example_events` id sequence is past 2^53, the public API still returns every id intact: ```bash curl "http://localhost:3000/api/@vitnode/example/content/events/big-launch" ``` ```json title="Response (trimmed)" { "id": "9007199254740994", "title": "Big launch", "slug": "big-launch", "primaryTag": { "id": "047d2c6c-1d86-47e2-bcd3-2df9f5359541" }, "tags": ["047d2c6c-1d86-47e2-bcd3-2df9f5359541"] } ``` `primaryTag` and `tags` point at `example.tag` records, so they carry UUIDs. Keep bigint ids as strings in your own code too. ## Valid ids [#valid-ids] Every route that takes an id parses it with the content type's strategy before touching the database. Anything else answers `400`, never a database error: | Strategy | Accepted | Refused, for example | | -------- | ---------------------------------------------------------------------------------------- | -------------------------------------- | | `serial` | A positive integer up to 2,147,483,647, or its digits in a URL | `abc`, `0012`, `-1` | | `bigint` | Positive decimal digits up to 9,223,372,036,854,775,807, without a sign or leading zeros | `0012`, `-1`, `9223372036854775808` | | `uuid` | Lowercase, hyphenated 8-4-4-4-12 hex | An uppercase UUID, `not-a-uuid`, `123` | Each record has exactly one spelling, so one record is never cached or indexed under two keys. ## Where ids appear [#where-ids-appear] Every Content Engine feature works with all three strategies: the public API, the AdminCP lists, editors, pickers and edit links, [public pages](/docs/content-engine/public-pages) and sitemaps, previews, schedules, revisions, [live editing](/docs/content-engine/live-editing), events, search, pagination cursors, [duplicate](/docs/content-engine/duplicate-content) and [hide](/docs/content-engine/content-visibility). - **Relations** use the key type of the record they point at. A bigint event that links to uuid tags gets a `uuid` foreign key and a `bigint`-to-`uuid` junction table. See [Relations across id strategies](/docs/content-engine/relations#relations-across-id-strategies). - **Shared core tables** that hold records of any content type, such as revisions, schedules, slug history, live editing drafts and the search index, store the id as text in a `varchar(64)` `itemId` column. See [Database](/docs/content-engine/database#ids-and-shared-tables). - **Events** type `contentId` by strategy: `number` for serial, `string` for uuid and bigint. - **Sitemaps** page through records in key order. For a uuid content type that order is lexical, not creation order, and every record still appears once. - **Repeatable rows** keep their own `serial` ids, whatever the owner uses. User and file references stay integers. ## Helpers [#helpers] Import these from `@vitnode/core/content` when your own code handles ids: | Helper | Returns | Use it to | | -------------------------------------- | -------------------- | ---------------------------------------------------------------------------- | | `ContentIdOf` | `number` or `string` | Type an id of one content type | | `ContentId` | `number \| string` | Type an id in code that handles any content type | | `parseContentIdOf(definition, value)` | The id, or `null` | Validate an id from a request, a job payload or a URL | | `parseContentId(strategy, value)` | The id, or `null` | The same, when you hold only the strategy | | `contentIdParamSchema(strategy)` | A Zod schema | Validate a path or query parameter. A serial id becomes a number | | `contentIdSchema(strategy)` | A Zod schema | Validate an id inside a JSON body | | `contentAnyIdSchema` | A Zod schema | Accept an id of any strategy, never rounding a bigint | | `contentIdKey(id)` | `string` | Store an id in a text column, cache key or log. Serial ids keep their digits | | `contentIdFromKey(strategy, key)` | The id, or `null` | Turn a stored key back into an id | | `compareContentIds(strategy, a, b)` | `number` | Sort ids the way Postgres does | `CONTENT_SERIAL_MAX` (`2147483647`) and `CONTENT_BIGINT_MAX` (`"9223372036854775807"`) are exported too. A custom route that reads an id is shown in [Services](/docs/content-engine/services#hide-duplicate-and-content-ids). ## Change the strategy later [#change-the-strategy-later] The strategy is part of the table's schema, and the engine does not convert existing data. Don't change `idStrategy` on a content type that has records and then run `db:migrate`. The generated SQL cannot turn integer keys into UUIDs. To switch a live content type, write the data migration yourself: 1. Add the new key column and fill it for every row. 2. Convert every column that references the old key: to-one relation columns in other content types, junction tables (`itemId` and `relatedItemId`), the translations table's `itemId` and repeatable child tables' `itemId`. 3. Rewrite the keys stored for that content type in the shared tables: `core_content_revisions`, `core_content_schedules`, `core_content_slug_history`, `core_search_index`, `core_content_drafts`, `core_content_field_locks`, `core_content_documents` and `core_ai_translation_sources`. 4. Swap the primary key and foreign key constraints, then change `idStrategy` and check that generating migrations again produces no further changes. Old URLs and API clients that stored the previous ids stop working, so plan redirects if ids appear in public URLs. Creating a new content type and copying the records into it is often simpler. # Introduction (/docs/content-engine) The Content Engine turns one TypeScript definition into structured content for your plugin. You describe the fields of an article or a category, and VitNode generates the database table, Zod validation, staff-only API routes, staff permissions and AdminCP screens. Optional blocks add drafts, a public API, pages with SEO metadata, revisions, scheduling, live editing, translations, search, hiding and duplication. This is the whole definition behind the example plugin's **Categories** screen: ```ts title="plugins/example/src/content/category.ts" import { defineContentType, field } from "@vitnode/core/content"; export const categoryContentType = defineContentType({ id: "example.category", tableName: "example_categories", fields: { name: field.text({ required: true, minLength: 1, maxLength: 100 }), }, admin: { path: "example/categories", list: { columns: ["name", "createdAt"], orderableFields: ["name"], }, }, }); ``` Its sibling `example.article` turns on more blocks. Same engine, more fields, a busier list: ## What you get [#what-you-get] | From the definition | VitNode generates | | ------------------- | -------------------------------------------------------------------------------------- | | `fields` | A Postgres table with system columns and indexes, Zod schemas and a typed service | | `admin` | An AdminCP list with search, sorting and bulk actions, plus create and edit forms | | Every content type | Staff routes and the `can_view`, `can_create`, `can_edit` and `can_delete` permissions | | `publication` | Draft and published states, a `can_publish` permission and **Publish** buttons | | `publicApi` | Read-only public routes that return only the fields you list | | `delivery` | Page URLs, SEO metadata, slug redirects and sitemap entries | | `editorial` | Revisions with restore, preview links and scheduling | | `liveEditing` | Field locks, an autosaved shared draft and presence in the AdminCP edit form | | `localization` | A translations table and per-language fields and publishing | | `search` | Records in the site [search](/docs/content-engine/search) index | | `visibility` | **Hide** and **Unhide** actions and a `can_hide` permission | | `duplication` | A **Duplicate** action that copies a record into a new draft | Content types live in code and in your migrations, not in the database. There is no screen for creating a content type at runtime. ## Pick a guide [#pick-a-guide] | You want to | Guide | | -------------------------------------------------------- | --------------------------------------------------------------------- | | Build your first content type, with its AdminCP screen | [First content type](/docs/content-engine/create-a-content-type) | | Add drafts and a read-only public API | [Public API](/docs/content-engine/public-api) | | Understand how public reads are cached and refreshed | [Caching](/docs/content-engine/caching) | | Give each record its own page with SEO metadata | [Public pages](/docs/content-engine/public-pages) | | Control titles, descriptions, noindex and the sitemap | [SEO](/docs/content-engine/seo) | | Make records findable in the site search | [Search](/docs/content-engine/search) | | Link records, group fields or repeat rows | [Relations](/docs/content-engine/relations) | | Organize records into boards, sections or categories | [Containers](/docs/content-engine/containers) | | Show a container tree and its content on the site | [Containers on the frontend](/docs/content-engine/container-frontend) | | Translate content into several languages | [Translations](/docs/content-engine/localization) | | Store and render formatted text | [Rich text](/docs/content-engine/rich-text) | | Keep revisions, share previews or schedule publishing | [Editorial](/docs/content-engine/editorial) | | Let several editors work on one record at the same time | [Live editing](/docs/content-engine/live-editing) | | Take a record off the public site without unpublishing | [Hide content](/docs/content-engine/content-visibility) | | Let editors copy a record as a new draft | [Duplicate content](/docs/content-engine/duplicate-content) | | Key records by UUID or bigint instead of serial integers | [Record ID strategies](/docs/content-engine/id-strategy) | | Change list columns, form sections or field components | [AdminCP](/docs/content-engine/admincp) | | Read and write content from your own API routes | [Services](/docs/content-engine/services) | | React to created, updated or published records | [Events](/docs/content-engine/events) | | Understand the generated tables and ship a schema change | [Database](/docs/content-engine/database) | | Check a content type before it goes live | [Production](/docs/content-engine/production) | ## Reference [#reference] - [Options](/docs/content-engine/reference): every `defineContentType` option and how the options depend on each other. - [Fields](/docs/content-engine/fields): every `field.*` helper with its options, column type and form control. - [Plugin files](/docs/content-engine/plugin-files): the files and exports the app and the API read from your plugin. - [Live editing API](/docs/content-engine/live-editing-api): the HTTP API and deployment requirements behind live editing. # Live editing API (/docs/content-engine/live-editing-api) The AdminCP drives [live editing](/docs/content-engine/live-editing) for you. This page is for the cases where you need the details: deploying it, calling its routes from your own code, or building a form layout that shows who is editing. Examples use `example.article`, whose staff API lives at `/api/@vitnode/example/admin/content/article`. ## Deployment requirements [#deployment-requirements] Live editing runs on two channels. Field locks and the shared draft are plain HTTP routes, so they work everywhere. Presence and rich text co-editing travel over the [WebSocket](/docs/dev/websocket) at `/api/ws`, which only a long-lived Node API server provides, such as `apps/api` or a [self-hosted](/docs/dev/deployments/self-hosted) install. | Deployment | Field locks and autosave | Presence | Rich text | | ------------------------------------------------------------------ | ---------------------------- | -------- | ----------------------------------------------- | | Long-lived Node API server with the WebSocket | Live, pushed over the socket | Yes | Co-edited | | No WebSocket, such as [Vercel](/docs/dev/deployments/cloud/vercel) | Polled over HTTP every 10 s | No | One editor at a time, locked like a plain field | A form without a socket polls `GET /{id}/locks` and `GET /{id}/draft` every 10 seconds, on top of lock renewals. Every request counts against the [rate limiter](/docs/dev/advanced/rate-limiter), which is keyed by IP address. A newsroom behind one office IP can reach the default of 80 requests a minute. A refused lock request leaves the field without autosave, so raise `rateLimiter.points` if that is you. With more than one API instance, set `REDIS_URL`. Instances share presence and document updates over Redis pub/sub. Without it, editors connected to different instances do not see each other. ## HTTP routes [#http-routes] The routes live under the content type's staff API module. Every route needs an AdminCP session and the type's `can_edit` permission, and answers `404` for a record that does not exist. | Method and path | Body | Success | Errors | | -------------------------- | --------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | `GET /{id}/locks` | | `{ locks }`, the unexpired locks | | | `POST /{id}/locks` | `{ field, locale, action }` | `{ lock }`, or `{ lock: null }` on release | `409` `CONTENT_FIELD_LOCKED`, `400` for an unknown field or wrong locale | | `GET /{id}/draft` | | `{ shared, translations }` | | | `PUT /{id}/draft` | `{ locale, values }` | `{ updatedAt }` | `409` `CONTENT_FIELD_NOT_LOCKED`, `400` `CONTENT_DRAFT_WRONG_SCOPE` or `CONTENT_DRAFT_INVALID` | | `POST /{id}/draft/discard` | `{}` | `{ discarded: true }`, and a `reset` with reason `discarded` to the room | | - `action` is `acquire`, `renew` or `release`. - `locale` is `null` for a field that is not localized and an enabled language code for a localized one. A shared field and a localized field never share a draft write. - A draft write accepts only fields you currently hold a lock on, and validates each value with the field's own rules. It never touches the record; **Save** does that. Taking a lock on the excerpt: ```http title="Request" POST /api/@vitnode/example/admin/content/article/2/locks Content-Type: application/json { "field": "excerpt", "locale": null, "action": "acquire" } ``` ```json title="200" { "lock": { "expiresAt": "2026-10-10T11:12:14.701Z", "field": "excerpt", "locale": null, "user": { "id": 16, "name": "Anna Kowalska" } } } ``` When someone else asks for the same field, the `409` names the holder: ```json title="409" { "code": "CONTENT_FIELD_LOCKED", "lock": { "expiresAt": "2026-10-10T11:12:14.701Z", "field": "excerpt", "locale": null, "user": { "id": 16, "name": "Anna Kowalska" } } } ``` Reading the draft returns the shared fields and one draft per language: ```json title="GET /api/@vitnode/example/admin/content/article/2/draft" { "shared": { "baseVersion": 3, "updatedAt": "2026-10-10T10:57:20.381Z", "updatedBy": { "id": 16, "name": "Anna Kowalska" }, "values": { "title": "Spring menu launches Monday at noon" } }, "translations": {} } ``` `baseVersion` is the record or translation version the draft was written on. ## WebSocket channel [#websocket-channel] The socket side is one channel, `@vitnode/core_content_live`, on the shared `/api/ws` connection. Joining a record's room checks the same AdminCP session and `can_edit` as the HTTP routes. Every message carries the record as `{ contentTypeId, itemId }`, and every client message carries the `clientId` of the tab that sent it. | Direction | Messages | | --------- | --------------------------------------------------------------------------------------------------------------------------- | | Client | `join`, `focus`, `heartbeat`, `leave`, and `doc:open`, `doc:update`, `doc:awareness`, `doc:close` for rich text | | Server | `joined`, `presence`, `locks`, `draft`, `reset`, `error`, and `doc:seed`, `doc:state-vector`, `doc:update`, `doc:awareness` | Rich text documents are [Yjs](https://yjs.dev) documents, one per record, field and language. Updates travel as base64. The protocol types live in `@vitnode/core/content/live/protocol` if you need them, but the AdminCP is the only client you should need. ## Timings [#timings] | What | Value | | ----------------------------------------------- | ---------- | | Lock lifetime without renewal | 60 s | | Lock renewal while the field has focus | every 20 s | | Autosave after the last keystroke | 1.5 s | | Presence heartbeat | every 15 s | | Member dropped after missed heartbeats | 45 s | | Rich text document stored after the last change | 2 s | | Polling without a socket | every 10 s | | Untouched drafts and documents removed after | 30 days | ## Where the data lives [#where-the-data-lives] | Table | Holds | | -------------------------- | ----------------------------------------------------------------- | | `core_content_drafts` | The shared draft of plain fields, one row per record and language | | `core_content_field_locks` | Active field locks with their holder and expiry | | `core_content_documents` | The Yjs state of each rich text field, per record and language | Each table keys the record by its id as text in a `varchar(64)` `itemId`, so live editing works with every [id strategy](/docs/content-engine/id-strategy). The socket accepts a uuid or bigint id and checks it against the content type's strategy, refusing a malformed one. The daily `content-editorial-cleanup` [cron job](/docs/dev/cron) removes expired locks, documents untouched for 30 days, and drafts untouched for 30 days whose record has moved on since. A stale draft whose record has not changed is kept, because it is somebody's unsaved work. When an editor's last tab leaves a record, their locks go too. ## Use live state in a custom form layout [#use-live-state-in-a-custom-form-layout] A plugin that replaces the edit form with [its own layout](/docs/content-engine/admincp) still gets locks and outlines on every field it renders with `ContentFormField`. The rest of the live UI comes from `@vitnode/core/content/admin-form`: ```tsx title="plugins/example/src/views/admin/article-layout.tsx" import { ContentFormField, ContentLivePresence, ContentLiveStatus, } from "@vitnode/core/content/admin-form"; export const ArticleFormLayout = () => (

); ``` Register it with `forms: { layout: ArticleFormLayout }` in the type's `contentTypeAdmin(...)` entry, the way the blog plugin registers `BlogArticleFormLayout`. | Export | What it gives you | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ContentLivePresence` | Avatars of everyone else in the record. `max` sets how many show before **+N**, 5 by default | | `ContentLiveFieldPresence` | Avatars of the people in one `field` and `locale` | | `ContentLiveLanguagePresence` | Who is working in one `locale` | | `ContentLiveStatus` | The autosave state: **Saving…**, **Autosaved 5 minutes ago** (with an amber dot while the draft is not saved into the record), **Autosave failed** | | `useContentLive()` | The session: `session.members`, `session.locks`, `status` (`saving`, `savedAt`, `failed`, `dirty`) and `coEditing` | | `useContentRichTextReplace()` | `(field, locale, document) => void` that replaces a rich text field through the shared editor, so everyone sees it and it can be undone. `null` while rich text is not co-edited | All of them render nothing, or return `null`, outside a live form, so the same layout works for the create form. # Live editing (/docs/content-engine/live-editing) Live editing lets a team work on the same record at the same time without overwriting each other. Changes autosave to a shared draft, everyone sees who is in which field, plain fields are edited by one person at a time, and [rich text](/docs/content-engine/rich-text) fields are typed in together. ## Turn it on [#turn-it-on] Add `liveEditing: true` next to [`editorial`](/docs/content-engine/editorial). Live editing needs `editorial`, because field locks and the shared draft are measured against the record version it adds. Without it, `defineContentType` throws ``liveEditing needs `editorial` ``, and TypeScript flags the option first: ```ts title="plugins/example/src/content/article.ts" export const articleContentType = defineContentType({ id: "example.article", tableName: "example_articles", editorial: true, liveEditing: true, // [!code highlight] fields: { title: field.text({ required: true, minLength: 3, maxLength: 200 }), excerpt: field.textarea({ maxLength: 500, nullable: true }), }, }); ``` A live session starts when someone opens an existing record's edit form in the AdminCP. That needs three things: - An AdminCP session, from signing in at `/admin`. - The content type's `can_edit` permission. Someone who can only view the record does not join. - A saved record. The create form is not live, because there is nothing to share yet. Presence and rich text co-editing also need the API's [WebSocket](/docs/dev/websocket). Without it, autosave and field locks still work over HTTP, a little slower. [Deployment requirements](/docs/content-engine/live-editing-api#deployment-requirements) lists what each setup gets. ## What editors see [#what-editors-see] ### Presence [#presence] The form header shows an avatar for everyone else in the record, up to five and then **+N**. Hover or focus an avatar to read where that person is, such as "editing Title". A ring in their color means they are in a field right now. The field they are in gets an outline in their color with a name tag. When they move to another field, the outline glides after them, and nothing on the page shifts to make room. In a localized form, the language switcher marks the languages people are working in. You never see yourself, and one person in several tabs counts once. ### Field locks [#field-locks] Clicking into a plain field, such as a title, slug or category, takes a lock on that field in that language. Everyone else sees the field dimmed and read-only inside the editor's outline, and the value updates as they type. Screen readers announce "Anna Kowalska is editing". A lock lasts 60 seconds and renews every 20 seconds while the editor stays in the field. Leaving the field releases it, and so does closing the record. A lock nobody renews, say because a laptop went to sleep, expires on its own. ### Autosave and the shared draft [#autosave-and-the-shared-draft] About 1.5 seconds after you stop typing in a field you hold, the value is saved to the record's draft. Close the tab and it's still there, but readers don't see it yet. The header shows **Saving…** and then **Autosaved just now**, later **Autosaved 5 minutes ago**, or **Autosave failed** when the write failed. An amber dot in front means the draft holds changes the record doesn't have yet, and it stays until someone clicks **Save changes**. Hover it for a reminder. Changed your mind? **Discard** next to the autosave time throws the draft away after you confirm, and the form goes back to the last saved version. It is a team draft, so everyone editing the record goes back too, and they get a short note saying so. There is one draft per record and language, shared by the whole team. When you open the record, you see the draft, not only what was last saved. **Save** commits it through the usual [version check](/docs/content-engine/editorial#safe-concurrent-edits) and creates one revision. Autosave itself never creates revisions, emits no events and leaves search and caches alone. [Preview links](/docs/content-engine/editorial#preview-links) also ignore the draft until someone saves. ### Rich text co-editing [#rich-text-co-editing] Rich text fields are not locked and get no outline. Everyone in the same field and language types into one shared document and sees each other's caret with a name tag, plus a tint over the text they select. Undo only undoes your own changes. The example plugin's article has no rich text field, so this is the blog plugin's article editor: Each language has its own shared document. The first person to open a field fills it from the record. If the connection drops, the editor keeps what you type and sends it when the connection comes back. The server stores the document about two seconds after the last change, and **Save** writes its current content, everyone's edits included, to the record. ### Restores and deletes [#restores-and-deletes] Restoring a revision or deleting the record throws away its drafts, locks and shared documents. Everyone in the session gets a notice, and the form reloads with the new state. ## Check the result [#check-the-result] 1. Sign in at `/admin` as two staff members with `can_edit`, for example in two browser profiles. 2. Open the same record's edit form in both. 3. Click into **Title** in one window. The other window shows the outline and name tag, and the field turns read-only there. 4. Type a few words and wait two seconds. The other window shows the new value, and the header of the first says **Autosaved just now**. Building your own form layout, or calling the lock and draft routes yourself? See the [live editing API](/docs/content-engine/live-editing-api). # Translations (/docs/content-engine/localization) Localization stores chosen fields once per language, while every other field stays shared. An article's title and body get a Polish version, but whether it is featured stays one value. Translated values live in a second table, `{tableName}_translations`, with one row per record and language. This guide uses `example.localized-article` from the example plugin. ## Before you begin [#before-you-begin] The languages come from your app's `i18n.locales` in `vitnode.config.ts` (see [Languages & Localization](/docs/dev/i18n)) and from the languages created at install. `defaultLocale` must be one of them. A language turned off in the config stays readable in the AdminCP, but nobody can write to it and the public API does not serve it. ### Mark the translatable fields [#mark-the-translatable-fields] Add a `localization` block and set `localized: true` on each field that changes per language: ```ts title="plugins/example/src/content/localized-article.ts" export const localizedArticleContentType = defineContentType({ id: "example.localized-article", tableName: "example_localized_articles", // [!code ++:4] localization: { defaultLocale: "en", fallback: "default", }, publication: true, fields: { // [!code highlight:8] title: field.text({ localized: true, required: true, minLength: 3, maxLength: 200, }), slug: field.slug({ localized: true, source: "title" }), body: field.textarea({ localized: true, required: true }), featured: field.boolean({ defaultValue: false }), }, }); ``` `text`, `textarea`, `richText`, `slug`, `blocks` and whole `group` fields can be localized. Numbers, booleans, enums, dates, files, users, relations and repeatables are always shared. A slug and its `source` must both be localized or both shared, otherwise every language would get the same URL. `localized: true` without a `localization` block throws, and so does a `localization` block without a localized field. ### Export the translations table [#export-the-translations-table] ```ts title="plugins/example/src/database/localized-articles.ts" export const localizedArticleContent = createContentModel( localizedArticleContentType, ); export const example_localized_articles = localizedArticleContent.table; export const example_localized_articles_translations = // [!code ++:2] localizedArticleContent.translationTable; ``` Drizzle Kit only sees exported tables, so without this line the migration has no translations table. ### Build and migrate [#build-and-migrate] ```bash tab="bun" bun run build:plugins && bun run db:migrate ``` ```bash tab="pnpm" pnpm build:plugins && pnpm db:migrate ``` ```bash tab="npm" npm run build:plugins && npm run db:migrate ``` The localized columns move to `example_localized_articles_translations`, keyed by `(itemId, languageId)`. That table has its own `version`, `createdAt` and `updatedAt`, plus `status` and `publishedAt` when the type has publication. The migration does not copy existing values into the translations table. If the table already holds records, review the SQL before you apply it and add a step that copies them. ## Edit languages in the AdminCP [#edit-languages-in-the-admincp] There are no language tabs. Each localized field carries its own language selector, so an editor can fix the Polish title without leaving the form. The field first shows your AdminCP language if it has text, then the default language, then any language that has text. Shared fields have no selector. This is the blog plugin's category dialog, where `name` is `field.text({ localized: true })`: Saving the form sends the shared fields and every language you typed into in one request: `POST /localized` for a new record, `PUT /{id}/localized` for an existing one. The server writes them in one transaction. A new record must include its default language. A Polish-only edit does not touch the shared row, so it does not bump the record's version or expire the English cache. With publication, each language has its own status. Publishing the record publishes its languages too, and you can then unpublish one language alone. A translation is public only when both the record and that translation are published, and the record is not [hidden](/docs/content-engine/content-visibility). With `editorial`, each language also keeps its own revisions and preview links. The example plugin registers `example.localized-article` on the API only, so it has no AdminCP screen. Add it to the plugin's `adminContent` and `adminNav` content types to get the generated form shown above. ## Read a language from the public API [#read-a-language-from-the-public-api] The public API serves one language per request, chosen in this order: 1. The `?locale=` query parameter. A locale that the site does not serve returns `404`. 2. Otherwise the `Accept-Language` header. The response then carries `Vary: Accept-Language`. 3. Otherwise `defaultLocale`. ```bash curl -i "http://localhost:3000/api/@vitnode/example/content/localized-articles/witaj-content-engine?locale=pl" ``` ```http HTTP/1.1 200 content-language: pl {"title":"Witaj Content Engine","slug":"witaj-content-engine","body":"Jeden rekord, dwa języki.","featured":false,"publishedAt":"2026-10-10T10:57:12.452Z","locale":"pl"} ``` The `locale` property says which language the body is in. When the requested translation is missing or unpublished, `fallback: "default"` serves the default language instead, so `"locale"` becomes `"en"`. With `fallback: "none"` (the default), the API returns `404`. In a page loader, pass the route's locale through. This is the example plugin's localized article page: ```ts title="plugins/example/src/pages/localized-article-page.tsx" const detail = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "get", module: "content/localized-articles", path: "/{slug}", args: { params: { slug: encodeURIComponent(slug) }, query: { locale }, }, }); ``` Opening `/pl/localized-articles/witaj-content-engine` renders the Polish translation: Each translation can have its own slug and URL; [Public pages](/docs/content-engine/public-pages) covers localized URLs and `hreflang`. ## Translation routes [#translation-routes] `buildContentAdminModule` adds staff routes for each language under the content type's admin path. They use the same staff permissions as the record: | Route | Does | | ----------------------------------------------------------- | ------------------------------------------------------------ | | `GET /{id}/translations` | Lists the record's translations | | `GET`, `POST`, `PUT`, `DELETE /{id}/translations/{locale}` | Reads, creates, updates or deletes one language | | `POST /{id}/translations/{locale}/publish` and `/unpublish` | Changes one language's status. Needs publication | | `GET /{id}/translations/{locale}/revisions` | One language's history. Needs editorial | | `POST /{id}/translations/{locale}/preview` | A preview link for one language. Needs editorial preview | | `POST /localized`, `PUT /{id}/localized` | Saves shared fields and several languages in one transaction | Each translation write emits an event such as `content.example.localized-article.translation_created` or `translation_published`; see [Events](/docs/content-engine/events). ## Options [#options] | Name | Type | Required | Default | Description | | --------------- | ----------------------- | -------- | -------- | ---------------------------------------------------------------------- | | `defaultLocale` | `string` | Yes | | A language code such as `"en"` or `"pt-BR"`. Every record starts in it | | `fallback` | `"none"` \| `"default"` | No | `"none"` | What the public API serves when the requested language is missing | # Plugin files (/docs/content-engine/plugin-files) VitNode reads a plugin's content types from several small files instead of one big config. A different part of the app loads each file, so a public page never downloads the AdminCP's forms and a browser never sees your database code. [First content type](/docs/content-engine/create-a-content-type) writes each file step by step; this page is the lookup. ## Files at a glance [#files-at-a-glance] | File | Export | Read by | Holds | | --------------------------------------- | ---------------------------------- | ------------------------------------------ | ------------------------------------------------------------------ | | `src/content/.ts` | Any name | Every file below | The `defineContentType` definition. Safe in the browser | | `src/database/.ts` | Every table | Drizzle Kit, from `dist/src/database/*.js` | `createContentModel` and the generated tables. Server only | | `src/api/modules/admin/admin.module.ts` | Any name | `src/config.api.ts` | `buildContentAdminModule` inside a module named `admin` | | `src/config.api.ts` | The API plugin, `VitNodeApiPlugin` | The API, and the app's typed `fetcher` | The admin module, and `buildContentPublicModule` for public routes | | `src/admin/nav.tsx` | `adminNav` | The AdminCP layout, on every AdminCP page | `{ definition, icon }` per content type and container collection | | `src/admin/content.tsx` | `adminContent` | The content screens, loaded on demand | Screen registrations, custom cells, fields and form layouts | | `src/content.ts` | `contentTypes` | The web build and the API at startup | Every content type with `delivery` or `search` | | `src/routes.ts` | `routes` | The web build | The pages that serve `delivery` and `search` URLs | | `src/config.tsx` | The plugin | The app's `vitnode.config.ts` | Plugin id, `messages`, `localeFiles` and `routes` only | | `src/locales/en.json` | JSON | The app, through `localeFiles` | Labels for content types, fields and permissions | A content type with an AdminCP screen needs an entry in both `admin/nav` and `admin/content`. The first adds the sidebar link, the second the screen behind it. They are separate files so the sidebar stays small on every AdminCP page, while form and editor code loads only with the screen. Without custom cells, fields or layouts, `admin/content` can re-export the nav list: ```tsx title="src/admin/content.tsx" export { adminNav as adminContent } from "./nav"; ``` Once you customize a screen, build `adminContent` on its own and reuse the nav entries, as the example plugin does: ```tsx title="plugins/example/src/admin/content.tsx" import type { ContentFrontendPluginSource } from "@vitnode/core/lib/plugin"; import { CONFIG_PLUGIN } from "@/const"; import { exampleArticleNav, exampleCategoryNav, examplePageNav } from "./nav"; export const adminContent = { pluginId: CONFIG_PLUGIN.pluginId, contentTypes: [exampleArticleNav, exampleCategoryNav, examplePageNav], } satisfies ContentFrontendPluginSource; ``` ## How the app finds them [#how-the-app-finds-them] The app never imports these files by hand. Its Vite plugin resolves a fixed subpath of every plugin listed in `vitnode.config.ts` and writes the result into a generated file: | Subpath | Generated file | Used for | | -------------------------- | ----------------------------- | ----------------------------------------------------- | | `/admin/nav` | `src/admin-nav.gen.ts` | The AdminCP sidebar | | `/admin/content` | `src/content-registry.gen.ts` | The AdminCP content screens | | `/content` | `src/content-modules.gen.ts` | URL checks in the build and in the API | | `/config.api` | `src/api-registry.gen.ts` | Types for `fetcher`, imported with `import type` only | | `/routes` | `src/plugin-routes.gen.ts` | Plugin pages | This happens each time `vite dev` or `vite build` starts, and the dev server regenerates the files when a resolved module changes. A subpath that does not resolve is skipped without an error, because most plugins have no content types. That is also the usual reason a new screen does not show up: a wrong file path, a wrong export name, or a plugin that was not rebuilt. Resolution only works when the plugin id equals the npm package name and the package exports its `dist` folder. A generated plugin already has the right `exports`: ```json title="plugins/example/package.json" { "name": "@vitnode/example", "exports": { "./locales/*.json": "./src/locales/*.json", "./*": { "import": "./dist/src/*.js", "types": "./dist/src/*.d.ts", "default": "./dist/src/*.js" } } } ``` Tables are the exception. Drizzle Kit reads `node_modules//dist/src/database/*.js` directly for every plugin in the API config. Export each table from those files, or it never reaches a migration. [Database](/docs/content-engine/database#export-every-table) shows a model with several tables. ## Keep `config.tsx` small [#keep-configtsx-small] `config.tsx` is bundled with the document shell of every public page: ```tsx title="plugins/example/src/config.tsx" import { buildPlugin } from "@vitnode/core/lib/plugin"; import { CONFIG_PLUGIN } from "@/const"; import messages from "./locales"; import { routes } from "./routes"; export const examplePlugin = () => buildPlugin({ ...CONFIG_PLUGIN, localeFiles: { en: "@vitnode/example/locales/en.json", }, messages, routes, }); ``` Do not import `admin/nav` or `admin/content` here. The app loads `admin/nav` with the AdminCP layout and `admin/content` behind a dynamic `import()`, so form code arrives only with the screen that needs it. Pulling them into `config.tsx` would put the whole editing stack, rich text editor included, into every public page. `localeFiles` maps each language to your locale JSON so the app can load it. Without it nothing fails, but every label from your locale file is missing. ## `content.ts` and public URLs [#contentts-and-public-urls] A content type with `delivery` or `search` publishes URLs. List every such content type in `src/content.ts`. The example plugin lists all of its types, which is allowed: ```ts title="plugins/example/src/content.ts" import { advancedArticleContentType } from "@/content/advanced-article"; import { articleContentType } from "@/content/article"; import { categoryContentType } from "@/content/category"; import { localizedArticleContentType } from "@/content/localized-article"; import { pageContentType } from "@/content/page"; export const contentTypes = [ articleContentType, advancedArticleContentType, localizedArticleContentType, categoryContentType, pageContentType, ]; ``` Keep the module browser-safe: it imports definitions only, never `src/database`. The web build checks that one of your pages serves each URL, and the API refuses to start when a plugin publishes URLs that this module does not declare. See [Content URLs need a page](/docs/dev/i18n/localized-urls#content-urls-need-a-page). ## Errors [#errors] | Error or symptom | Cause | Fix | | ---------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | | A content type has no sidebar entry or screen | `admin/nav` or `admin/content` did not resolve, or the export name is wrong | Check the file path, the `adminNav` / `adminContent` export and rebuild the plugin | | A table is missing from the migration | The table is not exported from `src/database/*.ts`, or the plugin was not rebuilt | Export it and run `build:plugins` before `db:migrate` | | `content-module-missing` when the API starts | A content type has `delivery` or `search`, but `/content` does not resolve | Add `src/content.ts` with `export const contentTypes` | | `incomplete-content-types` when the API starts | `src/content.ts` leaves out a content type that publishes URLs, or declares it differently | Export the same definition the API registers in `contentTypes` | | `content-url-without-page` in `dev` or `build` | No page route serves a `delivery` or `search` URL | Add the page to `src/routes.ts`, or change the URL | | Labels show raw keys or field names | `localeFiles` is missing from `config.tsx`, or the key path is wrong | Add `localeFiles` and check the `content.` keys | # Production (/docs/content-engine/production) A content type that works on your machine needs a few more checks before real editors and visitors use it. Go through this list for every content type you ship. ## Expose only what you mean to [#expose-only-what-you-mean-to] - [ ] **Review `publicApi.fields`.** It is the allowlist for everything public: the public API, page metadata from `delivery` and the search index. A field not listed there never leaves the server. Keep internal notes, moderation flags and anything personal out of it. - [ ] **Keep `publication` on.** `publicApi` and `search` both refuse to load without it, and new records start as drafts, so nothing is public until someone publishes it. - [ ] **Treat search as public.** `search.titleField`, `descriptionField` and `contentFields` must be public fields, and `search.authorField` shows who wrote a record in search results. The example article lists eight of its own fields plus `publishedAt`. `code`, `views` and `author` stay private, because they are not in the list: ```ts title="plugins/example/src/content/article.ts" publicApi: { path: "articles", fields: [ "title", "slug", "excerpt", "featured", "category", "animation", "gallery", "noIndex", "publishedAt", ], }, ``` ## Grant the right permissions [#grant-the-right-permissions] - [ ] **Give staff only what they need** in **AdminCP → Staff**. Each content type gets `can_view`, `can_create`, `can_edit` and `can_delete`, plus `can_publish` with `publication`, `can_restore` with `editorial` and `can_hide` with [`visibility`](/docs/content-engine/content-visibility). - [ ] **Guard your own admin routes.** Generated routes check their permissions themselves. A custom route next to them needs its own `adminStaffPermission`, as shown in [Services](/docs/content-engine/services#example-3-a-feature-this-article-button). ## Ship the migration [#ship-the-migration] - [ ] Commit the migration that `pnpm build:plugins && pnpm db:migrate` generated together with the content type. - [ ] Run `db:migrate` as a deploy step. Production never migrates on startup. - [ ] Read the generated SQL when you change an existing content type. See [Database](/docs/content-engine/database). ## Configure what editorial features rely on [#configure-what-editorial-features-rely-on] - [ ] **Scheduled publishing** is a queue task, and the `process-queue` [cron job](/docs/dev/cron) drains the queue every minute. Make sure something calls your cron endpoint in production. - [ ] **Set `CRON_SECRET`** to your own random value. The API rejects the built-in default outside development, which stops cron runs and front-end revalidation calls. - [ ] **Preview links** are built from `VITNODE_WEB_URL` and `VITNODE_API_URL`, which default to localhost. Set both to your public URLs. If either is not a valid absolute URL, the API logs a warning at startup and previews stay off. - [ ] **Integrations send the version they read.** With `editorial`, a save with an outdated `expectedVersion` fails with `409 CONTENT_VERSION_CONFLICT` instead of overwriting someone else's work. - [ ] **A separate front end that caches public reads** is listed in `content.revalidateOrigins` with an `https` URL. See [Caching](/docs/content-engine/caching). - [ ] **Live editing** has its own deployment requirements, listed in the [Live editing API](/docs/content-engine/live-editing-api). ## Check content health [#check-content-health] **AdminCP → Advanced → Search** shows how much of each content type is in the search index. Use **Reindex** on a collection, or **Rebuild index**, after a bulk import or a failed sync. For a monitoring probe, core has a staff-only route that reports every content type, its search drift per language and failed scheduled effects. It needs the `can_view` permission of the `system` module: ```bash curl -b "vitnode_auth_admin=" \ http://localhost:8000/api/@vitnode/core/admin/debug/content/status ``` ```json { "healthy": false, "searchHealthy": false, "effectsHealthy": true, "contentTypes": [ { "contentTypeId": "example.article", "pluginId": "@vitnode/example", "features": { "editorial": true, "localization": false, "publicApi": true, "publication": true, "scheduling": true, "search": true }, "search": { "healthy": false, "expectedTotal": 1, "canonicalIndexedTotal": 2, "provider": { "name": "postgres", "healthy": false, "indexedTotal": 2, "verified": true } }, "schedules": { "pending": 0, "withErrors": 0, "failedEffects": 0 } } ] } ``` This excerpt shows two indexed documents for one published article, so search is not healthy until the collection is reindexed. `failedEffects` counts scheduled publishes that committed but whose event or search update failed. In your own code, `contentEngineDiagnostics(c)` from `@vitnode/core/content/server` returns the same object. ## Know the limits [#know-the-limits] - Content types are defined in code and shipped with migrations. There is no AdminCP screen for creating them at runtime. - A relation points at one content type. To link to several unrelated types, use one relation field per type. - `field.blocks()` is not in the generated form by default. Editors change it through [widgets](/docs/dev/widgets) or a custom field component. # Public API (/docs/content-engine/public-api) A content type is private until you opt in. This guide follows `example.article` from the example plugin. It gets a draft and a published state, and its published records become readable by anyone at `/api/@vitnode/example/content/articles`. You list exactly which fields leave the server. You need a content type with an AdminCP screen, like the one built in [Create a content type](/docs/content-engine/create-a-content-type). ### Turn on publication and the public API [#turn-on-publication-and-the-public-api] Add `publication` and `publicApi` to the definition. This excerpt leaves out the article fields this guide does not use: ```ts title="plugins/example/src/content/article.ts" export const articleContentType = defineContentType({ id: "example.article", tableName: "example_articles", fields: { title: field.text({ required: true, minLength: 3, maxLength: 200 }), slug: field.slug({ source: "title" }), excerpt: field.textarea({ maxLength: 500, nullable: true }), featured: field.boolean({ defaultValue: false }), author: field.user(), category: field.relation({ required: true, onDelete: "restrict", target: () => categoryContentType, }), }, publication: true, // [!code ++] // [!code ++:9] publicApi: { path: "articles", fields: ["title", "slug", "excerpt", "featured", "category", "publishedAt"], searchableFields: ["title", "excerpt"], orderableFields: ["publishedAt", "title"], filterableFields: ["category", "featured"], defaultOrderBy: "publishedAt", defaultOrder: "desc", }, }); ``` - `publication` adds a `status` column (`draft` or `published`, default `draft`), a `publishedAt` timestamp, a `can_publish` staff permission and **Publish** / **Unpublish** actions in the AdminCP. - `publicApi.fields` is an allowlist with no wildcard. It needs exactly one slug field, because the detail route finds records by slug. `status` and `field.user()` fields can never be listed, which is why `author` stays private. - Searchable, filterable and orderable fields must also be in `fields`. `publishedAt` is always orderable and is the default sort. - `path` is one lowercase URL segment and cannot be `admin`. `publicApi` without `publication` throws when the definition loads, so drafts cannot leak by accident. ### Register the public module [#register-the-public-module] Add `buildContentPublicModule` to the plugin's API config. The example plugin passes all five content models; one without `publicApi` is skipped: ```ts title="plugins/example/src/config.api.ts" import { buildContentPublicModule } from "@vitnode/core/content/server"; // [!code ++] import { articleContent } from "@/database/articles"; // [!code ++] export const exampleApiPlugin = () => buildApiPlugin({ pluginId: CONFIG_PLUGIN.pluginId, modules: [ adminModule, // [!code ++:4] buildContentPublicModule({ pluginId: CONFIG_PLUGIN.pluginId, contentTypes: [articleContent], }), ], }); ``` ### Label the publish permission [#label-the-publish-permission] Give the new permission a name next to the other article permissions. The `Status` and `Published at` columns need no strings, because the AdminCP derives them from the column names. ```json title="plugins/example/src/locales/en.json" { "@vitnode/example:article:can_publish": "Publish and unpublish articles" } ``` ### Build, migrate and restart [#build-migrate-and-restart] Run this from the workspace root, then restart `pnpm dev` so the API registers the new routes: ```bash tab="bun" bun run build:plugins && bun run db:migrate ``` ```bash tab="pnpm" pnpm build:plugins && pnpm db:migrate ``` ```bash tab="npm" npm run build:plugins && npm run db:migrate ``` The migration adds `status`, `publishedAt` and an `example_articles_status_published_at_idx` index. Existing rows become drafts. [Database](/docs/content-engine/database) covers migrations in detail. ### Publish an article [#publish-an-article] Open **AdminCP → Example → Articles**. New articles show a **Draft** badge. Click the paper plane **Publish** button at the end of a row: Confirm with **Yes, publish it**. The badge turns into **Published** and the article appears in the public API. The **Create Article** dialog also gets **Save as draft** and **Publish** buttons, and you can publish many rows at once with [bulk actions](/docs/content-engine/admincp#bulk-actions). ## Check the result [#check-the-result] Request the list. Filters are query parameters named after the field, and `orderBy` accepts the orderable fields: ```bash curl "http://localhost:3000/api/@vitnode/example/content/articles?featured=false&orderBy=title&order=asc&first=1" ``` ```json { "edges": [ { "title": "Hello Content Engine", "slug": "hello-content-engine", "excerpt": "A first article from the example plugin, served by the public API and rendered on its own page.", "featured": false, "category": { "id": 5 }, "publishedAt": "2026-10-10T10:55:34.335Z" } ], "pageInfo": { "totalCount": 1, "totalPages": 1, "currentPage": null, "pageSize": 1, "count": 1, "hasNextPage": false, "hasPreviousPage": false, "startCursor": "eyJjb2x1bW4iOiJ0aXRsZSIsImlkIjozLCJ2YWx1ZSI6IkhlbGxvIENvbnRlbnQgRW5naW5lIn0", "endCursor": "eyJjb2x1bW4iOiJ0aXRsZSIsImlkIjozLCJ2YWx1ZSI6IkhlbGxvIENvbnRlbnQgRW5naW5lIn0" } } ``` A relation comes back as `{ "id": 5 }`. A file field, such as the example's `gallery`, comes back as `{ id, name, url, mimeType, size, width, height }`, never as the raw file ID. Unpublish the article and request it by slug. A draft, a record scheduled for later and a slug that never existed all get the same `404`, so the API never confirms that a draft exists: ```bash curl -i http://localhost:3000/api/@vitnode/example/content/articles/hello-content-engine ``` ```text HTTP/1.1 404 Article not found. ``` ## Read the API from your plugin [#read-the-api-from-your-plugin] The [fetcher](/docs/dev/fetcher) types the routes from the plugin's API registry. The module is `content/` followed by `publicApi.path`. Put a helper like this anywhere in your plugin: ```ts title="featured-articles.ts" import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { z } from "zod"; const zodArticleCard = z.object({ excerpt: z.string().nullable(), publishedAt: z.string().nullable(), slug: z.string(), title: z.string(), }); export const fetchFeaturedArticles = async () => { const response = await fetcher({ plugin: "@vitnode/example", method: "get", module: "content/articles", path: "/", args: { query: { featured: true, first: 5 } }, }); if (response.status !== 200) { throw new Error(`Loading articles answered ${response.status}.`); } const { edges } = await response.json(); return z.array(zodArticleCard).parse(edges); }; ``` The path, the query and `pageInfo` are typed. Each record is a `Record`, so parse the fields you use with Zod, as the example's article page does. A content type without `publicApi` adds no module: `module: "content/categories"` is a compile error. An `orderBy` outside the allowlist type-checks but answers `400`. ## Public API routes [#public-api-routes] All routes are `GET` and live under `/api/{pluginId}/content/{publicApi.path}`. | Route | Returns | | -------------------------- | --------------------------------------------------------------------------------------------------------- | | `/` | Published records with `edges` and `pageInfo` | | `/{slug}` | One published record, or `404` | | `/preview/{token}` | A draft behind a signed link, only with [preview links](/docs/content-engine/editorial#preview-links) | | `/delivery/resolve/{slug}` | Whether a URL is a record, a redirect or nothing, only with [delivery](/docs/content-engine/public-pages) | | `/delivery/item/{id}` | Canonical URL and SEO metadata for one record, only with delivery | | `/delivery/sitemap` | Sitemap entries, only with `delivery.sitemap` | The list accepts `first` or `last` (at most 50, also the default), `cursor`, `page`, `search` over `searchableFields`, `orderBy`, `order` and one parameter per filterable field. A filterable [container field](/docs/content-engine/fields#container) also accepts `includeDescendants=true`, so `?board=4&includeDescendants=true` lists board 4 and every board below it; an unknown container answers `404`. See [Containers on the frontend](/docs/content-engine/container-frontend#add-the-board-page). A record is public only when its `status` is `published`, its `publishedAt` is set and not later than the database clock, and it is not [hidden](/docs/content-engine/content-visibility). Every `publicApi` option is in the [content type reference](/docs/content-engine/reference#publicapi). Next, give each article a web page with [Public pages](/docs/content-engine/public-pages), or see how these reads are cached in [Caching](/docs/content-engine/caching). To let signed-in members create and edit records through the same path, add [Public write](/docs/content-engine/public-write). # Public pages (/docs/content-engine/public-pages) Delivery turns a published record into a web page at a stable URL, such as `/articles/hello-content-engine`. The Content Engine resolves the URL, answers `404` for drafts, redirects retired slugs and builds the page's SEO metadata from fields you choose. Your plugin owns the page component, so the content type, its API and its URL stay in one plugin. The content type needs [publication and a public API](/docs/content-engine/public-api). This guide continues with `example.article`. ### Turn on delivery [#turn-on-delivery] Add a `delivery` block to the definition: ```ts title="plugins/example/src/content/article.ts" export const articleContentType = defineContentType({ id: "example.article", // [!code ++:10] delivery: { redirects: true, seo: { titleField: "title", descriptionField: "excerpt", noIndexField: "noIndex", openGraph: { titleField: "title", descriptionField: "excerpt" }, }, sitemap: { changeFrequency: "weekly", priority: 0.7 }, }, }); ``` - Every SEO field must also be in `publicApi.fields`, because the page renders it publicly. That is why the example lists `noIndex` there. - `noIndexField` names a boolean. When it is `true`, the page gets `noindex, nofollow` and the record leaves the sitemap. - `redirects` needs `editorial: true`, which the example article already has. `sitemap` needs `publication`. - The page URL defaults to `/{publicApi.path}/:slug`, so articles live at `/articles/:slug`. Set `delivery.path` to use another URL. It needs exactly one `:slug` and cannot start with `/admin` or `/api`. ### Export the plugin's content types [#export-the-plugins-content-types] Export every content type with public URLs from `src/content.ts`: ```ts title="plugins/example/src/content.ts" import { advancedArticleContentType } from "@/content/advanced-article"; import { articleContentType } from "@/content/article"; import { categoryContentType } from "@/content/category"; import { localizedArticleContentType } from "@/content/localized-article"; import { pageContentType } from "@/content/page"; export const contentTypes = [ articleContentType, advancedArticleContentType, localizedArticleContentType, categoryContentType, pageContentType, ]; ``` The build compares these URLs with your plugin's routes. A content type whose URL no page serves stops `dev` and `build` with a `content-url-without-page` error, so a broken canonical link never ships. [Plugin files](/docs/content-engine/plugin-files) explains how the build finds this module. ### Claim the URL [#claim-the-url] Add a page for the same path to the plugin's routes: ```ts title="plugins/example/src/routes.ts" export const routes = definePluginRoutes([ // [!code ++:4] page("/articles/:slug", { component: lazy(() => import("./pages/article-page")), messages: ["@vitnode/example.articles"], }), ]); ``` ### Write the page [#write-the-page] The loader calls two public routes in parallel. `/delivery/resolve/{slug}` says whether the URL is a record, an old slug to redirect, or nothing. `/{slug}` returns the record's public fields. ```tsx title="plugins/example/src/pages/article-page.tsx" import { definePluginRoute, type PluginRoutePageProps, } from "@vitnode/core/routing"; import { contentDeliveryPage, contentDeliveryPageHead, } from "@vitnode/core/tanstack/content"; import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { z } from "zod"; import { CONFIG_PLUGIN } from "@/const"; import { ContentArticle } from "./content-article"; const zodArticle = z.object({ excerpt: z.string().nullable(), publishedAt: z.string().nullable(), title: z.string(), }); const loadArticle = async (slug: string) => { const [resolution, detail] = await Promise.all([ fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "get", module: "content/articles", path: "/delivery/resolve/{slug}", args: { params: { slug: encodeURIComponent(slug) } }, }), fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "get", module: "content/articles", path: "/{slug}", args: { params: { slug: encodeURIComponent(slug) } }, }), ]); if (resolution.status !== 200) { throw new Error( `Resolving the article "${slug}" answered ${resolution.status}.`, ); } return contentDeliveryPage({ item: detail.status === 200 ? zodArticle.parse(await detail.json()) : null, resolution: await resolution.json(), }); }; type ArticlePageData = Awaited>; export const route = definePluginRoute({ load: async ({ params }) => await loadArticle(params.slug), head: ({ loaderData }) => contentDeliveryPageHead(loaderData?.metadata, { title: loaderData?.item.title, }), }); const ArticlePage = ({ loaderData: { item }, }: PluginRoutePageProps) => ( ); export default ArticlePage; ``` - `contentDeliveryPage` returns `{ item, metadata }`. It throws a not-found for an unknown slug or a draft, and a `308` redirect for a retired slug. - `contentDeliveryPageHead` sets the title, the meta description (HTML stripped, cut at 160 characters), `robots` for a no-index record and `hreflang` alternates for localized content. - `load` comes before `head`, so TypeScript can infer `loaderData`. `ContentArticle` is the plugin's own layout component. ## Check the result [#check-the-result] Run `pnpm build:plugins`, restart `pnpm dev` and open `http://localhost:3000/articles/hello-content-engine`. Delivery adds no columns, so there is nothing to migrate. The page head carries the article's title and excerpt: ```bash curl -s http://localhost:3000/articles/hello-content-engine | grep -oE '[^<]*|' ``` ```html Hello Content Engine - VitNode ``` The resolve route shows what the loader received. `openGraph`, `canonicalPath` and `hreflang` are there too if you want to render more tags yourself: ```bash curl http://localhost:3000/api/@vitnode/example/content/articles/delivery/resolve/hello-content-engine ``` ```json { "type": "content", "canonicalPath": "/articles/hello-content-engine", "canonicalInternalPath": "/articles/hello-content-engine", "seo": { "title": "Hello Content Engine", "description": "A first article from the example plugin, served by the public API and rendered on its own page." }, "openGraph": { "title": "Hello Content Engine", "description": "A first article from the example plugin, served by the public API and rendered on its own page." }, "robots": { "follow": true, "index": true }, "alternates": [], "hreflang": { "languages": {} }, "isFallback": false, "itemId": null, "locale": null, "requestedLocale": null } ``` `itemId` is `null` because `id` is not in the article's `publicApi.fields`. Unpublish the article and the same URL shows the app's not-found page. ## Keep old URLs working [#keep-old-urls-working] Renaming a slug breaks links people already shared. With `delivery.redirects`, the old slug is stored in `core_content_slug_history` when an editor changes it, and the resolve route answers `{ "type": "redirect", "status": 308, "location": "/articles/new-slug" }`. `contentDeliveryPage` turns that into a `308` redirect. While a record is [hidden](/docs/content-engine/content-visibility), its page and its old slugs answer `404` instead. ## Sitemap entries [#sitemap-entries] `delivery.sitemap` lists every published URL for crawlers. [SEO](/docs/content-engine/seo#sitemap) covers the route, paging and turning the entries into XML. ## Localized URLs [#localized-urls] Every URL delivery builds follows the app's [localized URL rules](/docs/dev/i18n/localized-urls): language prefixes, per-language domains and translated route segments. The blog plugin's posts are a working example. They are [localized](/docs/content-engine/localization) and live at `/blog/:slug`, and the web app translates that route for Polish: ```ts title="apps/web/src/vitnode.config.ts" i18n: { routePaths: { pl: { '/blog/:slug': '/wpisy/:slug', }, }, }, ``` The blog's sitemap then lists `/blog/english-title` for English and `/pl/wpisy/polish-title` for Polish, and only published translations become `hreflang` alternates. Every `delivery` option is in the [content type reference](/docs/content-engine/reference#delivery). # Public write API (/docs/content-engine/public-write-api) This page lists everything `publicWrite` accepts and everything its routes answer. For a guided setup, follow [Public write](/docs/content-engine/public-write). Examples use `example.discussion` from the example plugin, whose write routes live at `/api/@vitnode/example/content/discussions`. ## `publicWrite` options [#publicwrite-options] `publicWrite` is a block of `defineContentType` from `@vitnode/core/content`. Leave it out, or set it to `false`, to keep public writing off. ```ts title="plugins/example/src/content/discussion.ts" publicWrite: { ownership: { field: "author" }, create: { fields: ["title", "body"], status: "published" }, update: { fields: ["title", "body"] }, }, ``` | Name | Type | Required | Default | Description | | ----------------- | -------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------- | | `ownership.field` | field name | Yes | | A single, shared `field.user()`. The server stamps it with the signed-in user on create | | `create` | object | No | off | Adds `POST /`. At least one of `create` and `update` is required | | `create.fields` | field names | Yes | | Non-empty allowlist of [writable fields](#writable-fields). Must include every field a new record needs | | `create.status` | `"draft"` \| `"published"` | No | `"draft"` | What a new record starts as. The server decides; the payload never does | | `create.captcha` | `boolean` | No | `false` | Requires a [captcha](/docs/dev/captcha) token on every create, when a captcha provider is configured | | `update` | object | No | off | Adds `GET /{id}/edit` and `PATCH /{id}`, and registers the `can_edit` moderator permission | | `update.fields` | field names | Yes | | Non-empty allowlist of writable fields | | `update.own` | `boolean` | No | `true` | Lets the owner edit their own record while it is not hidden. With `false`, only moderators edit | The content type also needs: - **`publicApi`**, and therefore `publication`. Without it, `publicWrite` only accepts `false` at the type level and throws when the definition loads. - **No localized fields.** Public writes do not create translations yet, so a content type with `localization` cannot use `publicWrite`. The read and write allowlists are independent. A field can be writable without being in `publicApi.fields`, and the other way around. ### Writable fields [#writable-fields] `create.fields` and `update.fields` accept top-level, shared fields of these kinds, from `CONTENT_PUBLIC_WRITABLE_KINDS`: `boolean`, `container`, `dateTime`, `enum`, `number`, `relation`, `richText`, `slug`, `text`, `textarea` They never accept: | Field | Why | | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `file` | A file id names somebody's upload, and the upload routes are AdminCP-only | | `user` | A user id names a person. Ownership is stamped by the server instead | | `group`, `repeatable`, `blocks` | Each hides more fields or child rows behind one name, which a strict allowlist cannot describe | | A group leaf such as `"seo.title"` | Only top-level fields can be written publicly | | A slug with a `source` | Derived on the server. List its source field instead, so nobody can squat on another address | | A `localized: true` field | Public writes do not create translations yet | | The ownership field | Only the server sets the owner | | `id`, `createdAt`, `updatedAt`, `status`, `publishedAt`, `version`, `hiddenAt`, `hiddenBy`, `visibility` | Managed by the server | A `relation` is writable only when its target content type has a `publicApi`. On each request, every referenced record must also be published and not hidden. A `container` is writable in `create.fields` only. A member picks the container once, when they create the record; moving it later is a staff edit, so an author cannot drop their record into a container they could not post in. On each create, the server reads the container back inside the write's transaction and checks that it belongs to the field's collection. A missing or foreign container answers `400` with an `unavailable` issue on that field. See [Containers on the frontend](/docs/content-engine/container-frontend#let-members-pick-a-board). ### Moderator permission [#moderator-permission] A content type with `update` adds `can_edit` to its plugin's moderator permissions, under the content type's permission module, such as `discussion`. It shares the `@vitnode/example:discussion:can_edit` label with the admin permission. If the plugin declares that module under `permissionStaff.moderator` itself, the declared list wins. ## Generated routes [#generated-routes] The routes live in the public module, under `/api/{pluginId}/content/{publicApi.path}`, next to the [public read routes](/docs/content-engine/public-api#public-api-routes). Only the ones `publicWrite` enables are mounted, and the [fetcher](/docs/dev/fetcher) types them the same way: a `post` to a content type without `create` is a compile error. | Method and path | Enabled by | Body | Success | | ---------------- | ---------- | ----------------------------- | -------------------------------------------------------------------------- | | `POST /` | `create` | `{ values }` | `201` with the record | | `GET /{id}/edit` | `update` | | `200` with the record, drafts included, `Cache-Control: private, no-store` | | `PATCH /{id}` | `update` | `{ values, expectedVersion }` | `200` with the record | `GET /{id}/edit` and `PATCH /{id}` answer only for the owner and for moderators. There is no public delete, publish or hide route. A request passes these checks in order: the rate limit, the captcha (create only), the session, the body, then for an edit the owner or moderator check and the relation targets, all before anything is written. ### Request bodies [#request-bodies] Both bodies are strict JSON objects. A key outside the allowlist is refused, never dropped. | Body | Field | Rules | | ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `POST /` | `values` | The fields in `create.fields`. Required fields must be present; optional fields may be left out | | `PATCH /{id}` | `values` | Any non-empty subset of `update.fields`. Only the fields sent change | | `PATCH /{id}` | `expectedVersion` | Positive integer, required on an [editorial](/docs/content-engine/editorial#safe-concurrent-edits) content type and refused on any other | Each value uses the field's own validation, the same as in the AdminCP. A rich text field takes a ProseMirror document, and a relation takes an id, or an array of ids for `multiple: true`. ```http title="PATCH request" PATCH /api/@vitnode/example/content/discussions/1 Content-Type: application/json Cookie: vitnode_auth= { "values": { "title": "How do I add a widget zone below an article?" }, "expectedVersion": 2 } ``` ### Response record [#response-record] Every successful response is the same record shape: | Name | Type | Description | | ------------- | -------------------------- | -------------------------------------------------------------------------------------- | | `id` | `number` or `string` | A string for the `uuid` and `bigint` [ID strategies](/docs/content-engine/id-strategy) | | `slug` | `string` \| `null` | The value of the `publicApi` slug field, the key of `GET /{slug}` | | `status` | `"draft"` \| `"published"` | | | `publishedAt` | ISO date string \| `null` | | | `version` | `number` | Editorial content types only. Send it back as `expectedVersion` | | `values` | object | Every field in `create.fields` or `update.fields`, `null` when empty. Nothing else | ```json title="200" { "id": 1, "slug": "how-do-i-add-a-widget-zone-below-an-article", "status": "published", "publishedAt": "2026-10-13T09:12:44.512Z", "version": 3, "values": { "title": "How do I add a widget zone below an article?", "body": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "I want one under my article." } ] } ] } } } ``` ## Status codes [#status-codes] | Status | Body | When | | ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | | `200` | Record | `GET /{id}/edit` or `PATCH /{id}` succeeded | | `201` | Record | `POST /` succeeded | | `400` | Rejection, `CONTENT_INVALID_INPUT` | The body is not JSON, breaks a rule, names a field outside the allowlist, or links to a record that is not available | | `400` | Plain text | `create.captcha` is on and the captcha token is missing or invalid | | `401` | Rejection, `CONTENT_UNAUTHENTICATED` | No user session | | `403` | Rejection, `CONTENT_FORBIDDEN` | The record is publicly readable, but you are not its owner or a moderator | | `404` | Rejection, `CONTENT_NOT_FOUND` | The record does not exist, or it is a draft or hidden and you may not edit it | | `409` | Conflict | A unique value is taken, or the record changed since `expectedVersion` | | `429` | `{ error, retryAfter }` | The [rate limit](#rate-limit) is used up | Validation failures are `400`, the status every VitNode input error uses, not `422`. ### Rejection [#rejection] `400`, `401`, `403` and `404` answer with one JSON shape, `zodContentPublicWriteRejection` from `@vitnode/core/content`: ```ts type ContentPublicWriteRejection = { code: | "CONTENT_FORBIDDEN" | "CONTENT_INVALID_INPUT" | "CONTENT_NOT_FOUND" | "CONTENT_UNAUTHENTICATED"; contentTypeId: string; issues: { code: string; field: string | null; message: string }[]; }; ``` `issues` is empty for `401`, `403` and `404`. For `400`, each issue names the field it belongs to, or `null` for the request as a whole. Translate an issue by its `code`; `message` is English text for developers. A title that is too short and an owner the client tried to set: ```json title="400" { "code": "CONTENT_INVALID_INPUT", "contentTypeId": "example.discussion", "issues": [ { "code": "too_small", "field": "title", "message": "Too small: expected string to have >=3 characters" }, { "code": "not_writable", "field": "author", "message": "This field cannot be written." } ] } ``` A body that is not JSON: ```json title="400" { "code": "CONTENT_INVALID_INPUT", "contentTypeId": "example.discussion", "issues": [ { "code": "invalid_json", "field": null, "message": "The body must be JSON." } ] } ``` If discussions had a `category` relation, a draft, hidden or missing category would all get the same answer: ```json title="400" { "code": "CONTENT_INVALID_INPUT", "contentTypeId": "example.discussion", "issues": [ { "code": "unavailable", "field": "category", "message": "The selected record is not available." } ] } ``` A member editing somebody else's published discussion: ```json title="403" { "code": "CONTENT_FORBIDDEN", "contentTypeId": "example.discussion", "issues": [] } ``` The same member editing somebody else's draft gets `404` with `"code": "CONTENT_NOT_FOUND"`, so the answer never confirms that the draft exists. ### Conflict [#conflict] `409` answers with `zodContentConflict`, the same shape the AdminCP's editorial routes use: ```json title="409 version conflict" { "code": "CONTENT_VERSION_CONFLICT", "contentTypeId": "example.discussion", "currentVersion": 4, "expectedVersion": 3, "itemId": 1 } ``` ```json title="409 unique conflict" { "code": "CONTENT_UNIQUE_CONFLICT", "contentTypeId": "example.discussion", "itemId": null } ``` `itemId` is `null` for a unique conflict on create. On `example.discussion`, a unique conflict means the slug derived from the title is taken. ### Rate limit [#rate-limit] `POST` and `PATCH` requests to a path containing `/content/`, outside `/admin/`, share a budget of 20 requests per 60 seconds per IP, on top of the global limit. Change it with `rateLimiter.contentWrite` in `apps/api/src/vitnode.api.config.ts`. It is off when `NODE_ENV=development`. See [Rate limiter](/docs/dev/advanced/rate-limiter) for the `429` body and Redis-backed counters. ### Codes [#codes] | Constant | Value | | -------------------------------------------- | -------------------------- | | `CONTENT_PUBLIC_WRITE_CODES.invalidInput` | `CONTENT_INVALID_INPUT` | | `CONTENT_PUBLIC_WRITE_CODES.unauthenticated` | `CONTENT_UNAUTHENTICATED` | | `CONTENT_PUBLIC_WRITE_CODES.forbidden` | `CONTENT_FORBIDDEN` | | `CONTENT_PUBLIC_WRITE_CODES.notFound` | `CONTENT_NOT_FOUND` | | `CONTENT_CONFLICT_CODES.version` | `CONTENT_VERSION_CONFLICT` | | `CONTENT_CONFLICT_CODES.unique` | `CONTENT_UNIQUE_CONFLICT` | Issue codes: | Code | Source | Meaning | | ------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- | | `not_writable` | `CONTENT_PUBLIC_WRITE_ISSUE_CODES.notWritable` | A key in `values` outside the allowlist. One issue per key | | `unavailable` | `CONTENT_PUBLIC_WRITE_ISSUE_CODES.unavailable` | A relation names a record that is missing, a draft or hidden | | `invalid_json` | `CONTENT_PUBLIC_WRITE_ISSUE_CODES.invalidJson` | The body is not JSON | | `too_small`, `too_big`, `invalid_type`, `invalid_value` | Zod | A value breaks the field's rules, such as `minLength` or an enum | | `custom` | Zod | A custom rule, such as an empty required rich text document or an update with no fields | | `unrecognized_keys` | Zod | A key beside `values`, such as `expectedVersion` on a content type without `editorial` | `parseContentPublicWriteRejection(body)` takes the parsed JSON body and returns the rejection, or `null` for any other shape. Unlike `parseContentConflict`, it does not take a string. ```ts import { parseContentPublicWriteRejection } from "@vitnode/core/content"; const rejection = parseContentPublicWriteRejection( await res.json().catch(() => null), ); ``` ## Server API [#server-api] Use these from `@vitnode/core/content/server` when a plugin needs its own write route, such as "start a discussion from a question", with the same ownership, authorization and effects as the generated routes. ### `createContentPublicWriteService` [#createcontentpublicwriteservice] ```ts createContentPublicWriteService({ c, model, pluginId }); ``` `c` is the Hono context, `model` is the content model, such as `discussionContent`, and `pluginId` is the plugin that owns the content type. The service acts as the user session of `c`, never as an AdminCP session. | Method | Returns | Behavior | | ------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `create(values)` | `Promise` | Validates `values` against `create.fields`, stamps the owner, checks relation targets, creates and, when the policy says so, publishes in one transaction. Emits events and syncs search after the commit | | `findEditable(id)` | `Promise` | Reads one record for its owner or a moderator, drafts included | | `update(id, body)` | `Promise` | Validates `{ values, expectedVersion }`, locks the row, authorizes, checks relation targets and writes in one transaction. Emits events and syncs search after the commit | The methods throw instead of answering: | Error | When | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `ContentPublicWriteDenied` | `reason` is `"unauthenticated"`, `"forbidden"` or `"notFound"`. Also `"notFound"` when `create` or `update` is off | | `ContentPublicWriteInputError` | A relation target is not available. Carries `field` and `detail` | | `ZodError` | `values` or the body breaks the allowlist or a field rule | | `ContentVersionConflict` | `expectedVersion` is out of date (editorial content types) | | Postgres unique violation | A unique value is taken | A route that starts a discussion from a single question. `withHttpErrors` turns a unique conflict into the structured `409`, and the `catch` maps a refusal to its status: ```ts title="plugins/example/src/api/modules/discussions/ask.route.ts" import { buildRoute } from "@vitnode/core/api/lib/route"; import { ContentPublicWriteDenied } from "@vitnode/core/content"; import { createContentPublicWriteService, withHttpErrors, } from "@vitnode/core/content/server"; import { HTTPException } from "hono/http-exception"; import { z } from "zod"; import { CONFIG_PLUGIN } from "@/const"; import { discussionContent } from "@/database/discussions"; export const askRoute = buildRoute({ pluginId: CONFIG_PLUGIN.pluginId, route: { method: "post", path: "/ask", description: "Start a discussion from a question", withCaptcha: true, request: { body: { required: true, content: { "application/json": { schema: z.object({ question: z.string().trim().min(3).max(200) }), }, }, }, }, responses: { 201: { content: { "application/json": { schema: z.object({ id: z.number(), slug: z.string().nullable() }), }, }, description: "Discussion started", }, 401: { description: "Not signed in" }, 409: { description: "A discussion with this title exists" }, }, }, handler: async c => { const { question } = c.req.valid("json"); const service = createContentPublicWriteService({ c, model: discussionContent, pluginId: CONFIG_PLUGIN.pluginId, }); try { const record = await withHttpErrors( "create", async () => await service.create({ title: question, body: { type: "doc", content: [ { type: "paragraph", content: [{ type: "text", text: question }], }, ], }, }), { contentTypeId: discussionContent.definition.id, structured: true }, ); return c.json({ id: record.id, slug: record.slug }, 201); } catch (error) { if (error instanceof ContentPublicWriteDenied) { throw new HTTPException(error.reason === "unauthenticated" ? 401 : 404); } throw error; } }, }); ``` A route outside `/content/` only gets the global rate limit, which is why this one asks for a captcha. ### Helpers [#helpers] | Function | Returns | Behavior | | ------------------------------------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `resolveContentPublicWriteActor(c)` | `{ type: "api", userId }` \| `null` | The signed-in user of the public session. Never an AdminCP session, never the body | | `authorizeContentPublicWrite(c, { action, actor, definition, pluginId, row })` | `{ allowed, via: "owner" \| "moderator" \| null }` | The owner and moderator rules above, for a stored `row`. `action` is `"update"` | | `contentPublicWriteRefusal(row)` | `"forbidden"` \| `"notFound"` | `"forbidden"` only when the public can already read `row` | | `resolveContentPublicationPolicy({ actor, container, definition, operation })` | `"draft"` \| `"published"` | The status a public create starts with. Today it returns `publicWrite.create.status`. `container` is the resolved container, or `null` | ## Definition errors [#definition-errors] `defineContentType` checks `publicWrite` when the definition loads and throws a `ContentEngineError` that starts with `[Content Engine] :`. Relation targets that were still loading are checked again when the routes are built at boot. | Problem | Error starts with | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | No `publicApi` | ``publicWrite needs `publicApi`.`` | | A localized content type | `publicWrite is not available on a localized content type yet.` | | Not an object or `false` | ``publicWrite is an options object or `false`.`` | | An unknown option | `publicWrite.x is not an option. publicWrite accepts: create, ownership, update.` | | `delete` | `publicWrite.delete is not supported.` | | `permissions`, `create.permission` or `update.permission` | `publicWrite.permissions is not an option.` | | No `ownership` | `publicWrite.ownership is required` | | `ownership.assignOnCreate` | `publicWrite.ownership.assignOnCreate is not an option.` | | `ownership.field` is unknown | `publicWrite.ownership.field references unknown field "x".` | | `ownership.field` is not a single, shared user field | ``publicWrite.ownership.field "x" must be a single, shared `field.user()`.`` | | Neither `create` nor `update` | `publicWrite enables nothing.` | | An empty `fields` list | `publicWrite.create.fields is empty. There is no wildcard` | | A field listed twice | `publicWrite.create.fields lists "x" twice.` | | A group leaf | `publicWrite.create.fields includes the leaf path "x".` | | A server-managed column | `publicWrite.create.fields includes "x", which the server manages.` | | The ownership field | `publicWrite.create.fields includes the ownership field "x".` | | An unknown field | `publicWrite.create.fields references unknown field "x".` | | A localized field | `publicWrite.create.fields includes the localized field "x".` | | A kind that cannot be written | `publicWrite.create.fields includes "x" of kind "file", which cannot be written publicly.` | | A slug with a `source` | `publicWrite.create.fields includes the slug "slug", which is derived from "title"` | | A relation whose target has no `publicApi` | `publicWrite.create.fields includes the relation "x", but its target "y" has no public API.` | | A required field missing from `create.fields` | `publicWrite.create.fields leaves out "x", which every new record needs.` | | A container field in `update.fields` | `publicWrite.update.fields includes the container field "x".` | | `create.status` is not a status | `publicWrite.create.status is "x". It is one of: draft, published.` | | `create.captcha` or `update.own` is not a boolean | ``publicWrite.create.captcha is `true` or `false`.`` | The field-list errors read `publicWrite.update.fields` for the `update` list. # Public write frontend (/docs/content-engine/public-write-frontend) This guide builds the two pages members use to write content: `/discussions/new` to start a discussion and `/discussions/:id/edit` to change one. Both call the [public write routes](/docs/content-engine/public-write) of `example.discussion` with the typed [fetcher](/docs/dev/fetcher), show field errors where they belong, and handle sign-in, permission and version problems. The finished pages are in the example plugin under `plugins/example/src/pages/`. The code below is the same, with some styling and helpers trimmed. ## Before you begin [#before-you-begin] You need a content type with `publicWrite`, registered in the public module, like the one built in [Public write](/docs/content-engine/public-write#enable-public-writing). The fetcher's `module` is `content/` plus `publicApi.path`, so every call here uses `module: "content/discussions"`. Routes, bodies and responses are inferred from that, and a `post` to a content type without `publicWrite.create` is a compile error. ### Add the routes [#add-the-routes] Register both pages in your plugin's `src/routes.ts`. The create page needs a signed-in visitor, so `requires: "authenticated"` sends guests to sign in first. The edit page handles a missing session itself, because the API decides who may edit: ```ts title="plugins/example/src/routes.ts" import { discussionSearch } from "./pages/discussion-search"; // [!code ++] export const routes = definePluginRoutes([ // [!code ++:16] page("/discussions/new", { component: lazy(() => import("./pages/discussion-new-page")), messages: ["@vitnode/example.discussions"], requires: "authenticated", }), page("/discussions/:id/edit", { component: lazy(() => import("./pages/discussion-edit-page")), messages: ["@vitnode/example.discussions"], }), page("/discussions/:slug", { component: lazy(() => import("./pages/discussion-page")), messages: ["@vitnode/example.articles", "@vitnode/example.discussions"], search: discussionSearch, }), ]); ``` `/discussions/:slug` is the read page the create form redirects to. It loads the discussion from the public `GET /{slug}` route like any [public page](/docs/content-engine/public-pages), and shows the success toast when the URL carries `?created=true`. Copy it from `plugins/example/src/pages/discussion-page.tsx`. ### Add the messages [#add-the-messages] The pages translate everything from the `discussions` namespace. Error messages are keyed by the API's codes, never by its English `message`: ```json title="plugins/example/src/locales/en.json" { "@vitnode/example": { "discussions": { "new": { "title": "Start a discussion", "desc": "Ask a question or share an idea. Everyone can read it as soon as you post it.", "submit": "Post discussion" }, "edit": { "title": "Edit discussion", "desc": "Changes are saved as a new revision, so nothing you replace is lost.", "submit": "Save changes", "success": { "title": "Changes saved", "desc": "\"{title}\" now shows your latest edits." }, "conflict": { "title": "Someone else edited this discussion", "desc": "It changed after you opened it. Reload to see the latest version - copy anything you want to keep first, because reloading discards your edits.", "reload": "Reload latest version" } }, "form": { "title": { "label": "Title", "min": "Use at least 3 characters", "max": "Keep it under 200 characters" }, "body": { "label": "Message", "desc": "Type / for headings, lists and more.", "required": "Write a message" } }, "state": { "unauthenticated": { "title": "Sign in to continue", "desc": "You need an account to start or edit a discussion.", "action": "Sign in" }, "forbidden": { "title": "You can't edit this discussion", "desc": "Only its author or a moderator can change it." }, "not_found": { "title": "Discussion not found", "desc": "It may have been removed, or the link is wrong." } }, "errors": { "title": "Couldn't save the discussion", "invalid": "Some details need another look.", "unauthenticated": "Your session has ended. Sign in again, then try once more.", "forbidden": "Only its author or a moderator can change this discussion.", "not_found": "This discussion no longer exists.", "unique": "A discussion with this title already exists. Try a different title.", "unknown": "Something went wrong on our side. Please try again.", "issues": { "not_writable": "This field can't be changed here.", "unavailable": "The selected item is no longer available." } } } } } ``` ### Build the shared form [#build-the-shared-form] Create `src/pages/discussion-form.tsx`. It holds the [AutoForm](/docs/ui/auto-form) both pages render and `useDiscussionRejection`, which turns a refusal into field errors and toasts: ```tsx title="plugins/example/src/pages/discussion-form.tsx" import type { AutoFormOnSubmit } from "@vitnode/core/components/form/auto-form"; import type { ContentPublicWriteRejection } from "@vitnode/core/content"; import { AutoForm, setFormFieldError, } from "@vitnode/core/components/form/auto-form"; import { AutoFormEditor } from "@vitnode/core/components/form/fields/editor"; import { AutoFormInput } from "@vitnode/core/components/form/fields/input"; import { emptyRichTextDocument, isRichTextEmpty, parseContentPublicWriteRejection, type RichTextDocument, zodRichTextDocument, } from "@vitnode/core/content"; import { toast } from "sonner"; import { useTranslations } from "use-intl"; import { z } from "zod"; const DISCUSSION_FIELDS = ["title", "body"] as const; type DiscussionField = (typeof DISCUSSION_FIELDS)[number]; export interface DiscussionFormValues { body: RichTextDocument; title: string; } const createDiscussionFormSchema = ( t: (key: "body.required" | "title.max" | "title.min") => string, defaults: DiscussionFormValues, ) => z.object({ title: z .string() .trim() .min(3, t("title.min")) .max(200, t("title.max")) .default(defaults.title), body: zodRichTextDocument .refine(doc => !isRichTextEmpty(doc), t("body.required")) .default(defaults.body), }); export type DiscussionFormSchema = ReturnType< typeof createDiscussionFormSchema >; export type DiscussionFormApi = Parameters< AutoFormOnSubmit >[1]; const isDiscussionField = (field: null | string): field is DiscussionField => DISCUSSION_FIELDS.some(name => name === field); const ISSUE_MESSAGE_KEYS = { not_writable: "issues.not_writable", unavailable: "issues.unavailable", } as const; const isKnownIssueCode = ( code: string, ): code is keyof typeof ISSUE_MESSAGE_KEYS => code in ISSUE_MESSAGE_KEYS; const REJECTION_MESSAGE_KEYS = { CONTENT_FORBIDDEN: "forbidden", CONTENT_INVALID_INPUT: "invalid", CONTENT_NOT_FOUND: "not_found", CONTENT_UNAUTHENTICATED: "unauthenticated", } as const satisfies Record; export const useDiscussionRejection = () => { const t = useTranslations("@vitnode/example.discussions.errors"); return async (response: Response, form: DiscussionFormApi) => { const rejection = parseContentPublicWriteRejection( await response.json().catch(() => null), ); const messageOf = (code: string) => t(isKnownIssueCode(code) ? ISSUE_MESSAGE_KEYS[code] : "invalid"); const unmatched = (rejection?.issues ?? []).filter(issue => { if (!isDiscussionField(issue.field)) return true; setFormFieldError(form, issue.field, messageOf(issue.code)); return false; }); if (rejection?.code === "CONTENT_INVALID_INPUT" && unmatched.length === 0) { return; } toast.error(t("title"), { description: rejection ? rejection.code === "CONTENT_INVALID_INPUT" ? messageOf(unmatched[0]?.code ?? "") : t(REJECTION_MESSAGE_KEYS[rejection.code]) : t("unknown"), }); }; }; export const DiscussionForm = ({ defaultValues = { body: emptyRichTextDocument(), title: "" }, isLeaving = false, onSubmit, submitLabel, }: { defaultValues?: DiscussionFormValues; isLeaving?: boolean; onSubmit: AutoFormOnSubmit; submitLabel: string; }) => { const t = useTranslations("@vitnode/example.discussions.form"); const formSchema = createDiscussionFormSchema(t, defaultValues); return ( ( ), }, { id: "body", component: props => ( ), }, ]} formSchema={formSchema} onSubmit={onSubmit} submitButtonProps={{ children: submitLabel, className: "self-start", disabled: isLeaving, }} /> ); }; ``` - `format="json"` makes the editor produce the ProseMirror document a [rich text field](/docs/content-engine/rich-text) stores. `isRichTextEmpty` catches a document with no text before the API does. - The client schema repeats the server's `minLength` and `maxLength` so members see mistakes before they submit. The server still validates everything. - Each issue has a `code`. Zod's own codes, such as `too_small`, and the public write codes `not_writable` and `unavailable` are stable, so translate by `code`. The `message` is English developer text. ### Add the create page [#add-the-create-page] Create `src/pages/discussion-new-page.tsx`. It sends `{ values }`, redirects to the new discussion on `201` and keeps the submit button busy while the page changes: ```tsx title="plugins/example/src/pages/discussion-new-page.tsx" import { type AutoFormOnSubmit, setFormFieldError, } from "@vitnode/core/components/form/auto-form"; import { definePluginRoute } from "@vitnode/core/routing"; import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { useState } from "react"; import { useTranslations } from "use-intl"; import { CONFIG_PLUGIN } from "@/const"; import { DiscussionForm, type DiscussionFormSchema, useDiscussionRejection, } from "./discussion-form"; const DiscussionNewBreadcrumb = () => { const t = useTranslations("@vitnode/example.discussions.new"); return {t("title")}; }; export const route = definePluginRoute({ head: ({ t }) => ({ description: t("@vitnode/example.discussions.new.desc"), robots: "noindex, nofollow", title: t("@vitnode/example.discussions.new.title"), }), breadcrumb: DiscussionNewBreadcrumb, }); const DiscussionNewPage = () => { const t = useTranslations("@vitnode/example.discussions"); const rejectDiscussion = useDiscussionRejection(); const [isLeaving, setIsLeaving] = useState(false); const onSubmit: AutoFormOnSubmit = async ( values, form, ) => { const res = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "post", module: "content/discussions", path: "/", args: { body: { values } }, }); if (res.status === 201) { const record = await res.json(); setIsLeaving(true); window.location.assign( record.slug === null ? `/discussions/${record.id}/edit` : `/discussions/${encodeURIComponent(record.slug)}?created=true`, ); return; } // The slug is derived from the title, so a unique conflict is the title's. if (res.status === 409) { setFormFieldError(form, "title", t("errors.unique")); return; } await rejectDiscussion(res, form); }; return (

{t("new.title")}

{t("new.desc")}

); }; export default DiscussionNewPage; ``` `AutoForm` shows a spinner on the submit button while `onSubmit` runs, and `isLeaving` keeps it disabled until the next page loads. The example's discussion page reads `?created=true` and shows the success toast there, because a full page load would drop a toast raised here. ### Add the edit page [#add-the-edit-page] Create `src/pages/discussion-edit-page.tsx`. Its loader reads the record with `GET /{id}/edit`, which answers only for the owner and moderators and includes drafts. Saving sends `PATCH /{id}` with the changed values and the record's `version`: ```tsx title="plugins/example/src/pages/discussion-edit-page.tsx" import { type AutoFormOnSubmit, setFormFieldError, } from "@vitnode/core/components/form/auto-form"; import { Alert, AlertDescription, AlertTitle, } from "@vitnode/core/components/ui/alert"; import { Button, buttonVariants } from "@vitnode/core/components/ui/button"; import { definePluginRoute, type PluginRoutePageProps, } from "@vitnode/core/routing"; import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { useState } from "react"; import { toast } from "sonner"; import { useTranslations } from "use-intl"; import { CONFIG_PLUGIN } from "@/const"; import { DiscussionForm, type DiscussionFormSchema, useDiscussionRejection, } from "./discussion-form"; const loadEditableDiscussion = async (param: string) => { const id = Number(param); if (!Number.isSafeInteger(id) || id < 1) { return { state: "notFound" as const }; } const res = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "get", module: "content/discussions", path: "/{id}/edit", args: { params: { id } }, }); if (res.status === 200) { return { record: await res.json(), state: "ready" as const }; } if (res.status === 401) return { id, state: "unauthenticated" as const }; if (res.status === 403) return { state: "forbidden" as const }; if (res.status === 404) return { state: "notFound" as const }; throw new Error(`Loading discussion ${id} for editing failed.`); }; type DiscussionEditData = Awaited>; type EditableDiscussion = Extract< DiscussionEditData, { state: "ready" } >["record"]; const DiscussionEditBreadcrumb = () => { const t = useTranslations("@vitnode/example.discussions.edit"); return {t("title")}; }; export const route = definePluginRoute({ load: async ({ params }) => await loadEditableDiscussion(params.id), head: ({ t }) => ({ robots: "noindex, nofollow", title: t("@vitnode/example.discussions.edit.title"), }), breadcrumb: DiscussionEditBreadcrumb, }); const DiscussionEditForm = ({ record }: { record: EditableDiscussion }) => { const t = useTranslations("@vitnode/example.discussions"); const rejectDiscussion = useDiscussionRejection(); // Every save bumps the version, so the next save has to send the new one. const [version, setVersion] = useState(record.version); const [hasConflict, setHasConflict] = useState(false); const onSubmit: AutoFormOnSubmit = async ( values, form, ) => { const res = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "patch", module: "content/discussions", path: "/{id}", args: { params: { id: record.id }, body: { values, expectedVersion: version }, }, }); if (res.status === 200) { const updated = await res.json(); setVersion(updated.version); setHasConflict(false); form.reset(values); toast.success(t("edit.success.title"), { description: t("edit.success.desc", { title: updated.values.title }), }); return; } if (res.status === 409) { const conflict = await res.json(); if (conflict.code === "CONTENT_VERSION_CONFLICT") { setHasConflict(true); } else { setFormFieldError(form, "title", t("errors.unique")); } return; } await rejectDiscussion(res, form); }; return ( <> {hasConflict && ( {t("edit.conflict.title")} {t("edit.conflict.desc")}

)} ); }; const PageShell = ({ children, description, title, }: { children?: React.ReactNode; description: string; title: string; }) => (

{title}

{description}

{children}

); const DiscussionEditPage = ({ loaderData, }: PluginRoutePageProps) => { const t = useTranslations("@vitnode/example.discussions"); if (loaderData.state === "unauthenticated") { const returnTo = encodeURIComponent(`/discussions/${loaderData.id}/edit`); return ( {t("state.unauthenticated.action")} ); } if (loaderData.state === "forbidden" || loaderData.state === "notFound") { const key = loaderData.state === "forbidden" ? "forbidden" : "not_found"; return ( ); } return ( ); }; export default DiscussionEditPage; ``` - The loader turns `401`, `403` and `404` into page states instead of errors. A stranger gets `403` for a published discussion and `404` for a draft or a hidden one, so the page never confirms that a draft exists. - `expectedVersion` exists only on [editorial](/docs/content-engine/editorial#safe-concurrent-edits) content types. When someone saved in between, the API answers `409` with `CONTENT_VERSION_CONFLICT` and writes nothing. The page keeps the member's text and offers a reload. - `PATCH` changes only the fields you send. A field you leave out keeps its stored value. ## Check the result [#check-the-result] Restart `pnpm dev` and sign in with a member account: 1. Open `/discussions/new`, type a two-letter title and submit. The title shows "Use at least 3 characters" without a request. 2. Write a real title and message and click **Post discussion**. You land on the new discussion with a **Discussion posted** toast. 3. Open `/discussions/1/edit`, change the title and click **Save changes**. A **Changes saved** toast appears. 4. Open the same edit page in a second tab, save in one tab, then save in the other. The second tab shows **Someone else edited this discussion**. 5. Sign in as a different member and open the edit page. It says **You can't edit this discussion**. Grant that member the moderator permission (see [Permissions](/docs/content-engine/public-write#permissions)) and it opens. {/* Image prompt: The /discussions/new page of the example plugin: "Start a discussion" heading, a Title input and a Message rich text editor, and a "Post discussion" button. Light theme, 1440x900. */} ## Ask for a captcha [#ask-for-a-captcha] With `create.captcha: true`, every create needs a captcha token, as long as a [captcha provider](/docs/dev/captcha) is configured. Pass the deployment's captcha config to `AutoForm` and forward the token it hands to `onSubmit`: ```tsx title="plugins/example/src/pages/discussion-new-page.tsx" import { useMiddlewareConfigQuery } from "@vitnode/core/tanstack/auth"; // [!code ++] const DiscussionNewPage = () => { const { data: config } = useMiddlewareConfigQuery(); // [!code ++] const onSubmit: AutoFormOnSubmit = async ( values, form, { captchaToken }, // [!code ++] ) => { const res = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "post", module: "content/discussions", path: "/", captchaToken, // [!code ++] args: { body: { values } }, }); // ...handle the response as before }; // ... }; ``` Then give `DiscussionForm` a `captcha` prop and pass `captcha={config.captcha}` to its `AutoForm`. A missing or failed token is a plain-text `400` from the captcha check, before the request reaches the write route. ## Custom UI [#custom-ui] The routes do not care how the form is built. Any form library, or none, works as long as you: 1. Send `{ values }` to `POST /`, or `{ values, expectedVersion }` to `PATCH /{id}`, with only the fields in the allowlist. A rich text field takes a ProseMirror document, not HTML. 2. On `400`, `401`, `403` or `404`, read the body with `parseContentPublicWriteRejection` from `@vitnode/core/content`. It takes the parsed JSON and returns the rejection, or `null` for any other shape. 3. On `409`, check `code` for `CONTENT_VERSION_CONFLICT` or `CONTENT_UNIQUE_CONFLICT`. This plain React form turns a textarea into paragraphs and puts each issue under its field: ```tsx title="plugins/example/src/pages/quick-discussion-form.tsx" import { parseContentPublicWriteRejection, type RichTextDocument, } from "@vitnode/core/content"; import { fetcher } from "@vitnode/core/tanstack/fetcher"; import { useState } from "react"; import { useTranslations } from "use-intl"; import { CONFIG_PLUGIN } from "@/const"; const toDocument = (text: string): RichTextDocument => ({ type: "doc", content: text .split(/\n{2,}/) .filter(part => part.trim() !== "") .map(part => ({ type: "paragraph", content: [{ type: "text", text: part }], })), }); export const QuickDiscussionForm = () => { const t = useTranslations("@vitnode/example.discussions"); const [errors, setErrors] = useState>({}); const [isPending, setIsPending] = useState(false); const onSubmit = async (event: React.SubmitEvent) => { event.preventDefault(); const data = new FormData(event.currentTarget); const text = (name: string) => { const value = data.get(name); return typeof value === "string" ? value : ""; }; setIsPending(true); const res = await fetcher({ plugin: CONFIG_PLUGIN.pluginId, method: "post", module: "content/discussions", path: "/", args: { body: { values: { title: text("title"), body: toDocument(text("body")), }, }, }, }); if (res.status === 201) { const record = await res.json(); window.location.assign(`/discussions/${record.id}/edit`); return; } setIsPending(false); if (res.status === 409) { setErrors({ title: t("errors.unique") }); return; } const rejection = parseContentPublicWriteRejection( await res.json().catch(() => null), ); if (rejection?.code !== "CONTENT_INVALID_INPUT") { setErrors({ form: rejection?.code === "CONTENT_UNAUTHENTICATED" ? t("errors.unauthenticated") : t("errors.unknown"), }); return; } setErrors( Object.fromEntries( rejection.issues.map(issue => [ issue.field ?? "form", issue.code === "unavailable" ? t("errors.issues.unavailable") : t("errors.invalid"), ]), ), ); }; return (

{t("form.title.label")} {errors.title && (

{errors.title}

)} {t("form.body.label")}

</label>
      {errors.body && (
        <p className="text-destructive text-sm" id="body-error">
          {errors.body}
        </p>
      )}

{errors.form && <p role="alert">{errors.form}</p>}

<button disabled={isPending} type="submit">
        {t("new.submit")}
      </button>
    </form>
  );
};
```

Every status, body and error code is listed in the [public write API reference](/docs/content-engine/public-write-api).

# Public write (/docs/content-engine/public-write)

`publicWrite` lets any signed-in member create records of a content type, and edit their own, through generated API routes on the public site. Staff keep the full AdminCP. Use it for discussions, reviews, listings or anything else your members write themselves.

This guide follows `example.discussion` from the example plugin: members start discussions at `/api/@vitnode/example/content/discussions`, edit their own, and moderators can edit anyone's.

## What public writing is [#what-public-writing-is]

The AdminCP and public writing are two doors into the same table. They differ in who may walk through them and what they may carry:

|                       | AdminCP routes                                  | Public write routes                                              |
| --------------------- | ----------------------------------------------- | ---------------------------------------------------------------- |
| Who                   | Staff with the content type's admin permissions | Any signed-in user creates; the owner or a moderator edits       |
| Session               | AdminCP session                                 | The user's normal session on the public site                     |
| Fields                | Every field                                     | Only the fields listed in `publicWrite`                          |
| Publish, hide, delete | Yes                                             | No. The server decides the status, and there is no public delete |
| Path                  | `/api/{pluginId}/admin/content/{type}`          | `/api/{pluginId}/content/{publicApi.path}`                       |

## Enable public writing [#enable-public-writing]

You need a content type with [publication and a public API](/docs/content-engine/public-api), because the write routes live beside the public read routes and a member has to be able to find what they wrote.

<Steps>

<Step>

### Define the content type [#define-the-content-type]

Create `src/content/discussion.ts`. The `publicWrite` block is the new part:

```ts title="plugins/example/src/content/discussion.ts"
import { defineContentType, field } from "@vitnode/core/content";

export const discussionContentType = defineContentType({
  id: "example.discussion",
  tableName: "example_discussions",

fields: {
    title: field.text({ required: true, minLength: 3, maxLength: 200 }),
    slug: field.slug({ source: "title" }),
    body: field.richText({ required: true }),
    author: field.user(),
  },

publication: true,
  visibility: true,
  editorial: { revisions: { retention: 20 } },

publicApi: {
    path: "discussions",
    fields: ["id", "title", "slug", "body", "publishedAt"],
  },

// [!code ++:5]
  publicWrite: {
    ownership: { field: "author" },
    create: { fields: ["title", "body"], status: "published" },
    update: { fields: ["title", "body"] },
  },

admin: {
    path: "example/discussions",
    titleField: "title",
  },
});
```

- `ownership.field` names a single `field.user()`. The server fills it with the signed-in user on create.
- `create.fields` and `update.fields` are allowlists with no wildcard. A field you add later stays private until you list it. `slug` is derived from `title` on the server, so you list `title` instead.
- `create.status` is what a new record starts as. It defaults to `"draft"`; discussions go live straight away.
- `update.own` defaults to `true`, so owners can edit their own records.

Every option and rule is in the [public write reference](/docs/content-engine/public-write-api#publicwrite-options).

</Step>

<Step>

### Create the model [#create-the-model]

Create `src/database/discussions.ts` and export the table so it reaches a migration:

```ts title="plugins/example/src/database/discussions.ts"
import { createContentModel } from "@vitnode/core/content/server";

import { discussionContentType } from "@/content/discussion";

export const discussionContent = createContentModel(discussionContentType);

export const example_discussions = discussionContent.table;
```

</Step>

<Step>

### Register the public module [#register-the-public-module]

Add the model to `buildContentPublicModule` in your API plugin. The module mounts the read routes and, because of `publicWrite`, the write routes:

```ts title="plugins/example/src/config.api.ts"
import { discussionContent } from "@/database/discussions"; // [!code ++]

export const exampleApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    modules: [
      adminModule,
      buildContentPublicModule({
        pluginId: CONFIG_PLUGIN.pluginId,
        contentTypes: [articleContent, discussionContent], // [!code highlight]
      }),
    ],
  });
```

The example plugin also adds `discussionContent` to its `admin` module and its AdminCP navigation, so staff can manage every discussion. That part is the same as in [Create a content type](/docs/content-engine/create-a-content-type#add-the-staff-api-routes).

</Step>

<Step>

### Label the permissions [#label-the-permissions]

A content type with `publicWrite.update` gets a `can_edit` **moderator** permission next to its usual admin permissions. Both share one label key:

```json title="plugins/example/src/locales/en.json"
{
  "@vitnode/example:discussion": "Discussions",
  "@vitnode/example:discussion:can_view": "View discussions",
  "@vitnode/example:discussion:can_create": "Create discussions",
  "@vitnode/example:discussion:can_edit": "Edit discussions",
  "@vitnode/example:discussion:can_delete": "Delete discussions",
  "@vitnode/example:discussion:can_publish": "Publish and unpublish discussions",
  "@vitnode/example:discussion:can_restore": "Restore an earlier version of a discussion",
  "@vitnode/example:discussion:can_hide": "Hide and unhide discussions"
}
```

</Step>

<Step>

### Build, migrate and restart [#build-migrate-and-restart]

Run this from the workspace root, then restart `pnpm dev` so the API registers the new routes:

```bash tab="bun"
bun run build:plugins && bun run db:migrate
```

```bash tab="pnpm"
pnpm build:plugins && pnpm db:migrate
```

```bash tab="npm"
npm run build:plugins && npm run db:migrate
```

</Tabs>

The migration creates `example_discussions` with an `author` column that references `core_users`. [Database](/docs/content-engine/database) covers migrations in detail.

</Step>

</Steps>

## Check the result [#check-the-result]

Sign in on the site, copy the value of your `vitnode_auth` cookie from the browser's developer tools, and create a discussion:

```bash
curl -i -X POST http://localhost:3000/api/@vitnode/example/content/discussions \
  -b "vitnode_auth=<session>" \
  -H "Content-Type: application/json" \
  -d '{"values":{"title":"How do I add a widget zone?","body":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"I want one under my article."}]}]}}}'
```

The API answers `201` with the new record. `version` is `2` because the create and the publish are each a version:

```json title="201"
{
  "id": 1,
  "slug": "how-do-i-add-a-widget-zone",
  "status": "published",
  "publishedAt": "2026-10-13T09:12:44.512Z",
  "version": 2,
  "values": {
    "title": "How do I add a widget zone?",
    "body": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "I want one under my article." }
          ]
        }
      ]
    }
  }
}
```

Now try to claim someone else's name. Send a short title and an `author`:

```bash
curl -i -X POST http://localhost:3000/api/@vitnode/example/content/discussions \
  -b "vitnode_auth=<session>" \
  -H "Content-Type: application/json" \
  -d '{"values":{"title":"Hi","author":2,"body":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Nice try."}]}]}}}'
```

Nothing is written, and each problem names its field:

```json title="400"
{
  "code": "CONTENT_INVALID_INPUT",
  "contentTypeId": "example.discussion",
  "issues": [
    {
      "code": "too_small",
      "field": "title",
      "message": "Too small: expected string to have >=3 characters"
    },
    {
      "code": "not_writable",
      "field": "author",
      "message": "This field cannot be written."
    }
  ]
}
```

Without the cookie, every write route answers `401` with `"code": "CONTENT_UNAUTHENTICATED"` before it reads the body. Validation failures are `400`, the status every VitNode input error uses, not `422`.

## Ownership [#ownership]

Every publicly written record has exactly one owner, and only the server sets it. On create, the routes take the user from the session and write it into `ownership.field` after validating the payload. The field can never appear in `create.fields` or `update.fields`, and a payload that sends it gets the `not_writable` issue above.

The owner never changes through the public routes, not even when a moderator edits the record. If the owner's account is deleted, the field becomes empty and nobody owns the record, so only moderators can edit it.

This is why `ownership` is required and not configurable: if a client could choose the owner, it could write as somebody else or take over their records.

## Permissions [#permissions]

Creating needs a signed-in user and nothing else. Editing is allowed for two kinds of people:

- **The owner**, while `update.own` is `true` (the default) and the record is not [hidden](/docs/content-engine/content-visibility). A record a moderator hid is the moderator's to restore, not the author's to keep editing. Set `update.own: false` to let only moderators edit.
- **Moderators** who hold the content type's `can_edit` moderator permission, directly or through a role.

To make someone a discussion moderator:

1. Open **AdminCP → Staff → Moderators** and click **Add Moderator**.
2. Pick a **Role** or a **User** and click **Add member**. The permission editor opens.
3. Choose **Restricted**, turn on **Edit discussions** under the example plugin, and click **Save changes**.

A moderator entry set to **Unrestricted**, and every root role, holds all moderator permissions, including this one.

Being staff is not enough on its own. The admin `can_edit` permission only opens the AdminCP routes, and an AdminCP session never adds powers on the public site: the public routes always act as the user's normal session. Moderators edit with the same forms and routes as members, so you build one edit page instead of two.

## Security [#security]

Each layer below holds even if the one before it has a bug:

- **Separate allowlists.** `publicWrite` fields are independent of `publicApi.fields`. A field can be writable without being public, and public without being writable. Server-managed columns (`id`, `status`, `publishedAt`, `version`, `hiddenAt` and friends), the owner field, file, user, group, repeatable and block fields can never be listed. See [writable fields](/docs/content-engine/public-write-api#writable-fields).
- **Strict schemas.** The request schemas are built from the allowlists alone. An unknown key is a `400`, never silently dropped.
- **Authentication.** An anonymous request gets `401` before its body is read.
- **Ownership** is stamped by the server, as described above.
- **Authorization under a row lock.** An edit reads the record with `SELECT ... FOR UPDATE`, checks the owner or moderator permission, and writes in the same transaction, so the owner that was checked is the owner that is written.
- **Relation targets.** A relation field is writable only when its target content type has a `publicApi`. On every write, each referenced record must be published and visible, otherwise the request is a `400` with the `unavailable` issue code. Missing, draft and hidden targets get the same answer.
- **No existence leaks.** `403` is only for records the public can already read. A draft or a hidden record answers `404`, like a record that does not exist.
- **Rate limit and captcha.** `POST` and `PATCH` requests under `/content/` share a budget of 20 per minute per IP, on top of the global limit. Set `create.captcha: true` to require a [captcha](/docs/dev/captcha) token on every create.
- **Session and CSRF.** The routes use the same session cookie, CORS and CSRF origin checks as every other VitNode API route, and they accept JSON bodies only.

Tune the write budget with `rateLimiter.contentWrite`. Like every rate limit, it is off when `NODE_ENV=development`:

```ts title="apps/api/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  rateLimiter: {
    // [!code ++]
    contentWrite: { points: 10, duration: 60 },
  },
});
```

## Events, search and revisions [#events-search-and-revisions]

Public writes trigger the same side effects as AdminCP writes, so nothing new needs wiring:

- [Events](/docs/content-engine/events): `created` on create, then `published` when `create.status` is `"published"`, and `updated` with `changedFields` on an edit that changed something. There are no separate public-write events.
- [Search](/docs/content-engine/search) is synced after the transaction commits, so a discussion published on create is searchable straight away.
- On an [editorial](/docs/content-engine/editorial#revisions) content type, each create and edit stores a revision attributed to the signed-in user, and staff can restore it from the AdminCP.

## Containers [#containers]

A content type organized into [containers](/docs/content-engine/containers), such as discussions in forum boards, lets members pick the container when they create a record: list the `field.container()` in `create.fields`. It cannot be in `update.fields`, so moving a record to another container stays a staff edit. The server resolves the container inside the write's transaction and refuses a missing or foreign one with a `400` on that field.

### Future container policies [#future-container-policies]

<Callout type="info" title="Not available yet">
  Per-container publication policies are planned, not shipped. Today every
  public create uses `publicWrite.create.status`.
</Callout>

Whether a new record starts as a draft or goes live is decided in one server-side function, `resolveContentPublicationPolicy`, and never by the payload. It already receives the signed-in user, the operation and the resolved container, so each container will be able to choose its own policy, such as "publish immediately" in one board and "wait for a moderator's approval" in another, without changing the routes or your forms.

Next, build the create and edit pages in [Public write frontend](/docs/content-engine/public-write-frontend).

# Options (/docs/content-engine/reference)

`defineContentType` from `@vitnode/core/content` takes one object that describes a content type and returns the resolved definition, with every default filled in. Use this page to look up an option. For a guided first build, follow [Create your first content type](/docs/content-engine/create-a-content-type).

## Minimal example [#minimal-example]

This is `example.article` from the example plugin, trimmed to the options most content types start with:

```ts title="plugins/example/src/content/article.ts"
import { defineContentType, field } from "@vitnode/core/content";

export const articleContentType = defineContentType({
  id: "example.article",
  tableName: "example_articles",
  fields: {
    title: field.text({ required: true, minLength: 3, maxLength: 200 }),
    slug: field.slug({ source: "title" }),
    excerpt: field.textarea({ maxLength: 500, nullable: true }),
  },
  publication: true,
  publicApi: {
    path: "articles",
    fields: ["title", "slug", "excerpt", "publishedAt"],
  },
  admin: {
    path: "example/articles",
    titleField: "title",
  },
});
```

## When options are checked [#when-options-are-checked]

Validation happens in two places, and both stop the app from starting:

- **`defineContentType`** checks one content type when its module is imported. Anything wrong in that object throws a `ContentEngineError`.
- **Plugin registration** checks every installed content type together, for things only the whole set can show: two types sharing a table or an AdminCP path. See [Unique across content types](#unique-across-content-types).

Every message starts with `[Content Engine] <id>:` and names the option at fault:

```txt
[Content Engine] example.article: publicApi needs `publication: true`. A public API without a draft state would put every row on the internet the moment it is created.
```

Many of these rules are type errors too, so your editor often complains before the app does.

## Top-level options [#top-level-options]

| Name           | Type                                    | Required | Default    | Description                                                                       |
| -------------- | --------------------------------------- | -------- | ---------- | --------------------------------------------------------------------------------- |
| `id`           | `string`                                | Yes      |            | `plugin.entity`, such as `example.article`. See [Names](#names)                   |
| `tableName`    | `string`                                | Yes      |            | Postgres table name, such as `example_articles`                                   |
| `fields`       | `Record<string, field>`                 | Yes      |            | At least one field built with a [`field.*` helper](/docs/content-engine/fields)   |
| `idStrategy`   | `"serial"` \| `"uuid"` \| `"bigint"`    | No       | `"serial"` | Type of the primary key. See [`idStrategy`](#idstrategy)                          |
| `admin`        | [`admin`](#admin)                       | No       | `{}`       | AdminCP path, list, form and title                                                |
| `publication`  | `boolean`                               | No       | off        | Draft and published states                                                        |
| `publicApi`    | [`publicApi`](#publicapi)               | No       | off        | Read-only public routes                                                           |
| `publicWrite`  | [`publicWrite`](#publicwrite)           | No       | off        | Create and edit routes for signed-in users. Needs `publicApi`                     |
| `delivery`     | `true` \| [`delivery`](#delivery)       | No       | off        | Public page URLs, SEO metadata, redirects and sitemap                             |
| `editorial`    | `true` \| [`editorial`](#editorial)     | No       | off        | Revisions, preview links and scheduling                                           |
| `liveEditing`  | `boolean`                               | No       | `false`    | [Live editing](#liveediting) in the AdminCP. Needs `editorial`                    |
| `localization` | [`localization`](#localization)         | No       | off        | A translation table for `localized: true` fields                                  |
| `search`       | [`search`](#search)                     | No       | off        | Site search indexing                                                              |
| `visibility`   | `boolean`                               | No       | off        | [Hide and unhide](#visibility) records. Needs `publication`                       |
| `duplication`  | `true` \| [`duplication`](#duplication) | No       | off        | A [Duplicate](#duplication) action that copies a record into a new draft          |
| `reports`      | `true` \| [`reports`](#reports)         | No       | off        | Readers can [report](#reports) published records to moderators. Needs `publicApi` |
| `indexes`      | [`indexes`](#indexes)                   | No       | `[]`       | Extra database indexes                                                            |

A feature block is on when it is present. `publicApi`, `publicWrite`, `localization` and `search` take an options object. `publication`, `liveEditing` and `visibility` are `true`, and `editorial`, `delivery` and `duplication` take `true` or an options object. Leave a block out, or set it to `false`, to keep it off. Write `true` or the object directly rather than a `boolean` variable, because the generated types read the literal to decide which columns and routes exist.

### Names [#names]

| Name                        | Rule                                                                                                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                        | Matches `/^[a-z0-9]+(?:\.[a-z0-9-]+)+$/`: lowercase, at least two dot-separated segments, dashes allowed after the first. At most 100 characters with `editorial` or `search`  |
| `tableName`                 | snake_case, starts with a letter, at most 63 characters                                                                                                                        |
| Field names                 | camelCase, start with a lowercase letter                                                                                                                                       |
| Reserved fields             | `id`, `createdAt` and `updatedAt` always. `status` and `publishedAt` with `publication`. `version` with `editorial`. `hiddenAt`, `hiddenBy` and `visibility` with `visibility` |
| Reserved for the list route | `cursor`, `first`, `last`, `order`, `orderBy` and `search`, because they are query parameters of the generated list route. Checked at plugin registration                      |
| Localized fields            | Cannot be named `itemId`, `languageId`, `version`, `createdAt` or `updatedAt` (translation table columns). A localized type cannot expose a public field called `locale`       |

Two names are derived from the id:

- The **entity key** is the id without its first segment, with further dots turned into `_`. `example.article` becomes `article`. Strings live under `{pluginId}.content.{entityKey}`, for example `@vitnode/example.content.article`.
- The **permission module** is the entity key with anything outside `a-z0-9` turned into `_`, so `example.localized-article` becomes `localized_article`. Permissions are named `@vitnode/example:article:can_view`. Override it with `admin.permissionModule`.

Every content type gets `can_view`, `can_create`, `can_edit` and `can_delete`. `publication` adds `can_publish`, `editorial` adds `can_restore` and `visibility` adds `can_hide`. Duplicating needs `can_create` and `can_view`, so `duplication` adds no permission.

## `admin` [#admin]

Controls the generated AdminCP screens. Guide: [Customize the AdminCP](/docs/content-engine/admincp).

| Name                    | Type                                   | Default                                                                    | Description                                                                                                                                                                |
| ----------------------- | -------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`                  | `string`                               | The id with dots as slashes (`example/article`)                            | Screen URL under `/admin/content/`. Lowercase segments of letters, digits and dashes, starting with a letter, joined by `/`. The last segment cannot be `create` or `edit` |
| `permissionModule`      | `string`                               | Derived from the id, see [Names](#names)                                   | Middle part of the permission names. snake_case                                                                                                                            |
| `titleField`            | field name \| `null`                   | First shared text or textarea field, then first localized one              | Names a record in headings, pickers and toasts. A localized field is shown in the reader's language. `null` means no title                                                 |
| `colorField`            | field name \| `null`                   | `null`                                                                     | A shared field holding a color, shown as a swatch beside the title                                                                                                         |
| `create.mode`           | `"dialog"` \| `"page"`                 | `"dialog"`                                                                 | Open the create form in a dialog or on its own page                                                                                                                        |
| `edit.mode`             | `"dialog"` \| `"page"`                 | `"dialog"`                                                                 | Same, for the edit form                                                                                                                                                    |
| `navigation`            | `boolean`                              | `true`                                                                     | `false` hides the AdminCP sidebar entry                                                                                                                                    |
| `list.columns`          | field names                            | `status` (with publication), every shared single-column field, `updatedAt` | Table columns, in order. Accepts localized fields, system columns and to-many relation or user fields                                                                      |
| `list.searchableFields` | field names                            | Shared text and textarea fields                                            | Fields the search box matches: text, textarea, richText or slug                                                                                                            |
| `list.orderableFields`  | field names                            | `[]`                                                                       | Sortable shared fields. System columns are always sortable and need no entry. No localized or file fields                                                                  |
| `list.defaultOrderBy`   | column name                            | `"updatedAt"`                                                              | A system column or one of `list.orderableFields`                                                                                                                           |
| `list.defaultOrder`     | `"asc"` \| `"desc"`                    | `"desc"`                                                                   |                                                                                                                                                                            |
| `list.thumbnailField`   | field name                             |                                                                            | A shared single `field.file()` drawn in the title cell. `titleField` must be one of `list.columns`                                                                         |
| `form.fields`           | field names                            | Every field except `field.blocks()`, in declaration order                  | Fields in the generated form                                                                                                                                               |
| `form.sections`         | `{ name: string; fields: string[] }[]` | `[]`                                                                       | Groups the form into titled sections. Cannot be combined with `form.fields`                                                                                                |

A section `name` is lowercase `a-z0-9_` and starts with a letter, because it is the key its heading is read from. Each field goes in one section only, and no section can be empty.

```ts title="plugins/blog/src/content/post.ts"
admin: {
  permissionModule: "posts",
  path: "blog/articles",
  titleField: "title",
  create: { mode: "page" },
  edit: { mode: "page" },
  list: {
    columns: ["title", "authorId", "status", "publishedAt", "updatedAt"],
    searchableFields: ["title"],
    thumbnailField: "coverImage",
  },
},
```

## `publication` [#publication]

`publication: true` adds the `status` (`"draft"` or `"published"`) and `publishedAt` columns, and the `can_publish` permission. It has no other options.

Publication on its own never makes anything public. Only [`publicApi`](#publicapi) does. Guide: [Publish content with a public API](/docs/content-engine/public-api).

```ts title="plugins/example/src/content/article.ts"
publication: true,
```

## `publicApi` [#publicapi]

Generates read-only routes at `/api/{pluginId}/content/{path}` that return published records only. Guide: [Publish content with a public API](/docs/content-engine/public-api).

| Name               | Type                | Required | Default         | Description                                                                                                                                                 |
| ------------------ | ------------------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`             | `string`            | Yes      |                 | One URL segment matching `/^[a-z][a-z0-9-]*$/`, at most 64 characters, not `admin`                                                                          |
| `fields`           | field names         | Yes      |                 | The allowlist, with no wildcard. Must contain exactly one top-level slug field. No duplicates                                                               |
| `searchableFields` | field names         | No       | `[]`            | Matched by `?search=`. Text, textarea, richText or slug fields. Rich text matches its words only                                                            |
| `filterableFields` | field names         | No       | `[]`            | Each becomes an equality query parameter. Boolean, container, enum, number, relation, slug or text fields. A container also takes `includeDescendants=true` |
| `orderableFields`  | field names         | No       | `[]`            | Accepted by `?orderBy=`. `publishedAt` is always added                                                                                                      |
| `defaultOrderBy`   | field name          | No       | `"publishedAt"` | Must be orderable                                                                                                                                           |
| `defaultOrder`     | `"asc"` \| `"desc"` | No       | `"desc"`        |                                                                                                                                                             |

What `fields` accepts:

- Fields of kind text, textarea, richText, slug, number, boolean, enum, dateTime, file, relation, container and blocks. A file is returned as its public descriptor, never as the file id. A container is returned as its id.
- The columns `id`, `createdAt`, `updatedAt` and `publishedAt`.
- Group and repeatable leaves one at a time, as `"seo.title"`. Naming the whole group throws, so a leaf added later stays private.
- Not `status` (every public row is published), and not `field.user()`, so an author is never published by accident.

`searchableFields`, `filterableFields` and `orderableFields` must all be in `fields`. Repeatable leaves fit none of them. `orderableFields` also refuses file fields, to-many relations and localized fields.

```ts title="plugins/example/src/content/article.ts"
publicApi: {
  path: "articles",
  fields: ["title", "slug", "excerpt", "featured", "category", "noIndex", "publishedAt"],
  searchableFields: ["title", "excerpt"],
  orderableFields: ["publishedAt", "title"],
  filterableFields: ["category", "featured"],
},
```

## `publicWrite` [#publicwrite]

Adds create and edit routes for signed-in users beside the `publicApi` routes, with an owner stamped by the server and a `can_edit` moderator permission. Guide: [Public write](/docs/content-engine/public-write). Every option, route and error: [Public write API](/docs/content-engine/public-write-api).

```ts title="plugins/example/src/content/discussion.ts"
publicWrite: {
  ownership: { field: "author" },
  create: { fields: ["title", "body", "board"], status: "published" },
  update: { fields: ["title", "body"] },
},
```

A [container field](/docs/content-engine/fields#container), such as `board`, may be in `create.fields` only. Moving a record to another container is a staff edit.

## `delivery` [#delivery]

Gives each published record a public page: canonical URL, SEO metadata, redirects from old slugs and a sitemap. Guides: [Public pages](/docs/content-engine/public-pages) and [SEO](/docs/content-engine/seo).

| Name                             | Type                                                                                          | Default                   | Description                                                                                                           |
| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `path`                           | `string`                                                                                      | `/{publicApi.path}/:slug` | The page route. Exactly one `:slug`, no other parameters or `*`, not under `/admin` or `/api`, at most 512 characters |
| `redirects`                      | `boolean`                                                                                     | off                       | Old slugs answer `308` with the current URL                                                                           |
| `seo.titleField`                 | text field                                                                                    |                           | Page title                                                                                                            |
| `seo.fallbackTitleField`         | text field                                                                                    |                           | Used when `titleField` is empty. Needs `titleField`                                                                   |
| `seo.descriptionField`           | text, textarea or richText field                                                              |                           | Meta description. Rich text becomes plain text, and the page trims it to 160 characters                               |
| `seo.fallbackDescriptionField`   | text, textarea or richText field                                                              |                           | Used when `descriptionField` is empty. Needs `descriptionField`                                                       |
| `seo.noIndexField`               | shared boolean field                                                                          |                           | `true` marks the page `noindex` and leaves it out of the sitemap                                                      |
| `seo.openGraph.titleField`       | text field                                                                                    |                           | `og:title`                                                                                                            |
| `seo.openGraph.descriptionField` | text, textarea or richText field                                                              |                           | `og:description`                                                                                                      |
| `sitemap`                        | `true` \| `{ changeFrequency, priority }`                                                     | off                       | Lists published URLs                                                                                                  |
| `sitemap.changeFrequency`        | `"always"` \| `"hourly"` \| `"daily"` \| `"weekly"` \| `"monthly"` \| `"yearly"` \| `"never"` |                           |                                                                                                                       |
| `sitemap.priority`               | `number`                                                                                      |                           | From 0 to 1 inclusive                                                                                                 |
| `hreflang.xDefault`              | `"defaultLocale"`                                                                             |                           | Adds an `x-default` alternate pointing at the default language                                                        |

Every SEO field must be in `publicApi.fields`, may be a group leaf such as `"seo.title"`, and cannot be a repeatable leaf. `noIndexField` must be shared, not localized.

```ts title="plugins/example/src/content/article.ts"
delivery: {
  redirects: true,
  seo: {
    titleField: "title",
    descriptionField: "excerpt",
    noIndexField: "noIndex",
    openGraph: { titleField: "title", descriptionField: "excerpt" },
  },
  sitemap: { changeFrequency: "weekly", priority: 0.7 },
},
```

## `editorial` [#editorial]

Adds a `version` column, revision history and the `can_restore` permission. [`liveEditing`](#liveediting) builds on it. Guide: [Revisions, previews and scheduling](/docs/content-engine/editorial).

| Name                       | Type                                           | Default | Description                                                                                                             |
| -------------------------- | ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `revisions.retention`      | `number`                                       | `50`    | Newest revisions kept per record. A whole number from 1 to 500                                                          |
| `preview`                  | `true` \| `{ expiresInMinutes, pathTemplate }` | off     | Signed [preview links](/docs/content-engine/editorial#preview-links) for drafts                                         |
| `preview.expiresInMinutes` | `number`                                       | `15`    | Link lifetime. A whole number from 1 to 1440                                                                            |
| `preview.pathTemplate`     | `string`                                       |         | Your own preview URL. Starts with `/`, contains `{token}` exactly once and no other placeholder, at most 512 characters |
| `scheduling`               | `boolean`                                      | off     | Publish or unpublish at a chosen time                                                                                   |

```ts title="plugins/example/src/content/article.ts"
editorial: {
  revisions: { retention: 20 },
  preview: { expiresInMinutes: 30 },
  scheduling: true,
},
```

## `localization` [#localization]

Creates a `{tableName}_translations` table for fields marked `localized: true`. Guide: [Translate content](/docs/content-engine/localization).

| Name            | Type                    | Default  | Description                                                                                           |
| --------------- | ----------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `defaultLocale` | `string`                |          | Required. The language every record is created in, such as `"en"` or `"pt-BR"`. At most 32 characters |
| `fallback`      | `"none"` \| `"default"` | `"none"` | `"default"` serves the default language when a translation is missing                                 |

Only text, textarea, richText, slug, blocks and group fields can be localized. A localized slug needs a localized source field, and a shared slug needs a shared one.

```ts title="plugins/example/src/content/localized-article.ts"
localization: {
  defaultLocale: "en",
  fallback: "default",
},
```

## `search` [#search]

Keeps published records in the [site search index](/docs/dev/search). Drafts never show up in public results. Guide: [Search](/docs/content-engine/search).

| Name               | Type        | Required | Description                                                                                                                           |
| ------------------ | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `titleField`       | field name  | Yes      | The result heading. A text field that is not nullable                                                                                 |
| `contentFields`    | field names | Yes      | The indexed body, at least one, no duplicates. Text, textarea, richText or slug. Repeatable leaves such as `"faq.answer"` are allowed |
| `pathTemplate`     | `string`    | Yes      | The result URL. Starts with `/`, contains `{slug}` exactly once, at most 512 characters                                               |
| `descriptionField` | field name  | No       | Shown in result excerpts. Text, textarea or richText                                                                                  |
| `authorField`      | field name  | No       | A top-level `field.user()` credited in the index. It does not have to be public                                                       |
| `imageField`       | field name  | No       | A shared single `field.file()` shown as the result image. Must be in `publicApi.fields`                                               |

Every field except `authorField` must be in `publicApi.fields`, or a result snippet would leak a private value. Leave the language out of `pathTemplate`, because your [i18n settings](/docs/dev/i18n) add the locale prefix.

```ts title="plugins/example/src/content/article.ts"
search: {
  titleField: "title",
  descriptionField: "excerpt",
  contentFields: ["title", "excerpt"],
  pathTemplate: "/articles/{slug}",
  authorField: "author",
},
```

## `visibility` [#visibility]

`visibility: true` adds the nullable `hiddenAt` and `hiddenBy` columns, the `can_hide` permission, the `POST /{id}/hide` and `POST /{id}/unhide` staff routes and a **Visibility** filter in the AdminCP list. A hidden record is left out of every public read while it keeps its `status` and `publishedAt`. It has no other options. Guide: [Hide content](/docs/content-engine/content-visibility).

```ts title="plugins/blog/src/content/post.ts"
publication: true,
visibility: true,
```

## `reports` [#reports]

`reports: true` lets signed-in readers report a published record. It registers a report target, adds `can_view_reports` and `can_manage_reports` to the moderator catalog, plus `can_view_hidden` and `can_hide` with `visibility`, and needs no migration. Pass `{ titleField, snapshotFields }` to choose what the report's snapshot keeps. Guide: [Enable reports](/docs/dev/moderation/enable-reports). Options: [Moderation reference](/docs/dev/moderation/reference#reports-on-a-content-type).

```ts title="plugins/blog/src/content/post.ts"
publicApi: { path: "blog", fields: ["id", "title", "friendlyUrl", "content"] },
reports: true,
```

## `duplication` [#duplication]

Adds a **Duplicate** action and the `POST /{id}/duplicate` staff route, which copy a record and its translations into a new draft. Pass `true`, or an object to change the title suffix. Guide: [Duplicate content](/docs/content-engine/duplicate-content).

| Name          | Type      | Default                                        | Description                                                                             |
| ------------- | --------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
| `titleSuffix` | `boolean` | On when `admin.titleField` is a `field.text()` | Adds a localized "(Copy)" to the copy's title. `true` with any other title field throws |

```ts title="plugins/blog/src/content/post.ts"
duplication: true,
```

## `idStrategy` [#idstrategy]

The type of the primary key. Every foreign key, junction column and translation `itemId` that points at the record takes the same type. Guide: [Record ID strategies](/docs/content-engine/id-strategy).

| Value                | Postgres key                              | In JSON            |
| -------------------- | ----------------------------------------- | ------------------ |
| `"serial"` (default) | `serial`                                  | A number           |
| `"uuid"`             | `uuid`, `DEFAULT gen_random_uuid()`       | A lowercase string |
| `"bigint"`           | `bigint GENERATED BY DEFAULT AS IDENTITY` | A decimal string   |

Any other value throws. Changing the strategy of a content type that already has records needs a [hand-written data migration](/docs/content-engine/id-strategy#change-the-strategy-later).

```ts title="plugins/example/src/content/event.ts"
idStrategy: "bigint",
```

## `indexes` [#indexes]

Extra database indexes on the base table. The engine already indexes slugs, `unique: true` text fields, foreign keys, `createdAt`, `updatedAt` and `(status, publishedAt)`. A declared index on the same columns replaces the generated one instead of adding a second. Guide: [Database and migrations](/docs/content-engine/database).

| Name     | Type       | Required | Default                                            | Description                       |
| -------- | ---------- | -------- | -------------------------------------------------- | --------------------------------- |
| `on`     | `string[]` | Yes      |                                                    | At least one column, no repeats   |
| `unique` | `boolean`  | No       | `false`                                            |                                   |
| `name`   | `string`   | No       | `{tableName}_{columns}_idx`, or `_key` when unique | snake_case, at most 63 characters |

`on` accepts shared fields, group leaves such as `"syndication.priority"`, and system columns (`id`, `createdAt`, `updatedAt`, plus `status`, `publishedAt` and `version` when their feature is on). It refuses localized fields, `field.blocks()`, repeatable leaves, to-many relations and file collections, and whole groups. Two indexes on the same columns throw.

```ts title="plugins/example/src/content/advanced-article.ts"
indexes: [{ on: ["syndication.priority"] }],
```

## `liveEditing` [#liveediting]

`liveEditing: true` lets several editors work on one record at once in the AdminCP edit form: field locks, an autosaved shared draft, presence and rich text co-editing. It needs `editorial`, because locks and drafts are measured against the record version. It adds the `/{id}/locks` and `/{id}/draft` staff routes. Guide: [Live editing](/docs/content-engine/live-editing).

```ts title="plugins/example/src/content/article.ts"
editorial: { revisions: { retention: 20 } },
liveEditing: true,
```

AI suggestions are not a `defineContentType` option. They are set per field with the `ai` option of `field.text()` and `field.textarea()`. See [Fields](/docs/content-engine/fields) and [AI actions](/docs/dev/ai/actions).

## Which options need which [#which-options-need-which]

Each row is a rule `defineContentType` enforces, with the start of the message it throws (after the `[Content Engine] <id>:` prefix).

| Option                                                              | Needs                                                    | Error                                                                                                      |
| ------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `publicApi`                                                         | `publication`                                            | ``publicApi needs `publication: true`.``                                                                   |
| `publicApi.fields`                                                  | Exactly one top-level slug field                         | `publicApi.fields must expose exactly one slug field`                                                      |
| `publicWrite`                                                       | `publicApi`                                              | ``publicWrite needs `publicApi`.``                                                                         |
| `publicWrite`                                                       | No localized fields                                      | `publicWrite is not available on a localized content type yet.`                                            |
| `search`                                                            | `publication`                                            | ``search needs `publication: true`.``                                                                      |
| `search`                                                            | `publicApi`                                              | ``search needs `publicApi: { path, fields }`.``                                                            |
| `search.*Field`, `search.contentFields`                             | The field in `publicApi.fields`                          | `search.titleField names "x", which is not in publicApi.fields.`                                           |
| `delivery`                                                          | `publicApi`                                              | ``delivery needs `publicApi: { path, fields }`.``                                                          |
| `delivery` on a localized type                                      | `"id"` in `publicApi.fields`                             | `delivery on a localized content type needs "id" in publicApi.fields.`                                     |
| `liveEditing`                                                       | `editorial`                                              | ``liveEditing needs `editorial`.``                                                                         |
| `delivery.redirects`                                                | `editorial`                                              | ``delivery.redirects needs `editorial`.``                                                                  |
| `delivery.redirects` on a localized type                            | A localized slug field                                   | `delivery.redirects needs a localized slug field on a localized content type, but "slug" is shared.`       |
| `delivery.hreflang`                                                 | `localization`                                           | ``delivery.hreflang needs `localization: { defaultLocale }`.``                                             |
| `delivery.seo.*`                                                    | The field in `publicApi.fields`                          | `delivery.seo.titleField names "x", which is not in publicApi.fields.`                                     |
| `delivery.seo.fallbackTitleField`                                   | `delivery.seo.titleField`                                | ``delivery.seo.fallbackTitleField is set without `titleField`.``                                           |
| `delivery.seo.fallbackDescriptionField`                             | `delivery.seo.descriptionField`                          | ``delivery.seo.fallbackDescriptionField is set without `descriptionField`.``                               |
| `editorial.preview`                                                 | `publicApi`                                              | ``editorial.preview needs `publicApi: { path, fields }`.``                                                 |
| `editorial.scheduling`                                              | `publication`                                            | ``editorial.scheduling needs `publication: true`.``                                                        |
| `visibility`                                                        | `publication`                                            | ``visibility needs `publication: true`.``                                                                  |
| `duplication.titleSuffix: true`                                     | `admin.titleField` pointing at a `field.text()`          | ``duplication.titleSuffix needs `admin.titleField` to be a text field``                                    |
| A `localized: true` field                                           | `localization`                                           | ``Field "title" is `localized: true` but the content type has no `localization: { defaultLocale }` block`` |
| `localization`                                                      | At least one `localized: true` field                     | ``localization is enabled but no field is marked `localized: true`,``                                      |
| Any block with an `enabled` key                                     | Nothing: a block is on when present                      | `publicApi.enabled is not an option.`                                                                      |
| `publication` or `liveEditing` as an object                         | `true` or `false`                                        | ``publication is `true` or `false`.``                                                                      |
| `visibility` as an object                                           | `true` or `false`                                        | ``visibility is `true` or `false`.``                                                                       |
| `admin.list.thumbnailField`                                         | `admin.titleField` in `admin.list.columns`               | `admin.list.thumbnailField is drawn in the title column, but admin.titleField`                             |
| `admin.form.sections`                                               | No `admin.form.fields`                                   | ``admin.form declares both `fields` and `sections`.``                                                      |
| `admin.list.defaultOrderBy`                                         | A system column or an `admin.list.orderableFields` entry | `admin.list.defaultOrderBy is "x", which is not in admin.list.orderableFields.`                            |
| `publicApi.defaultOrderBy`                                          | An orderable field                                       | `publicApi.defaultOrderBy is "x", which is not in publicApi.orderableFields.`                              |
| `publicApi.searchableFields`, `filterableFields`, `orderableFields` | The field in `publicApi.fields`                          | `publicApi.searchableFields includes "x", which is not in publicApi.fields.`                               |

### Unique across content types [#unique-across-content-types]

Plugin registration checks these across every installed content type:

| Value                                 | Unique within                 | Error starts with                          |
| ------------------------------------- | ----------------------------- | ------------------------------------------ |
| `id`                                  | The app                       | `Duplicate content type id`                |
| Table names, including generated ones | The database                  | `Table "x" is claimed by both`             |
| Index names, including generated ones | The database                  | `Index name "x" is used by both`           |
| `admin.path`                          | The app                       | `AdminCP path "x" is claimed by both`      |
| `permissionModule`                    | The plugin                    | `Permission module "x" is derived by both` |
| `publicApi.path`                      | The plugin                    | `Public path "x" is claimed by both`       |
| `publicApi.path` with `delivery`      | The app, among delivery types | `Delivery path "x" is claimed by both`     |

# Relations (/docs/content-engine/relations)

Relations connect one record to others, and two related helpers shape a record's own data. Everything lands in real tables, not a JSON blob: a relation is a foreign key, a to-many relation is a junction table, a group is a set of columns and a repeatable field is a child table. This guide walks through `example.advanced-article` from the example plugin, which uses all four.

## Before you begin [#before-you-begin]

You need a working content type to link to, such as `example.category` from [Create a content type](/docs/content-engine/create-a-content-type).

<Steps>

<Step>

### Link to one record [#link-to-one-record]

Point an article at a category with `field.relation`. `target` is a function, so two content types can refer to each other without an import cycle:

```ts title="plugins/example/src/content/article.ts"
import { categoryContentType } from "./category";

fields: {
  category: field.relation({ // [!code ++:5]
    required: true,
    onDelete: "restrict",
    target: () => categoryContentType,
  }),
},
```

Then tell `createContentModel` which column the foreign key references:

```ts title="plugins/example/src/database/articles.ts"
import { example_categories } from "./categories";

export const articleContent = createContentModel(articleContentType, {
  references: { category: () => example_categories.id }, // [!code ++]
});
```

`references` needs one entry per relation field. A missing or extra key is a type error. `field.user()`, `field.file()` and `self: true` relations find their table on their own and need no entry.

</Step>

<Step>

### Link to many records [#link-to-many-records]

Add `multiple: true`. The advanced article has two to-many relations: a set of categories and an ordered "read next" list that points back at articles:

```ts title="plugins/example/src/content/advanced-article.ts"
fields: {
  categories: field.relation({
    multiple: true,
    onDelete: "restrict",
    target: () => categoryContentType,
  }),
  relatedArticles: field.relation({
    multiple: true,
    onDelete: "cascade",
    ordered: true,
    self: true,
  }),
},
```

`ordered: true` keeps the order editors arrange. Without it, the set is stored in ascending id order. `onDelete: "cascade"` on a to-many relation drops the link when the target is deleted, and `"restrict"` refuses the delete. A to-many relation cannot be `required` or `nullable`; use `min: 1` to demand at least one target.

Each to-many field gets a junction table with `itemId`, `relatedItemId`, `position` and `createdAt`. Give `categories` its reference and export both junction tables, or Drizzle Kit leaves them out of the migration:

```ts title="plugins/example/src/database/advanced-articles.ts"
export const advancedArticleContent = createContentModel(
  advancedArticleContentType,
  { references: { categories: () => example_categories.id } },
);

export const example_advanced_articles = advancedArticleContent.table;
export const example_advanced_articles_categories = // [!code ++:4]
  advancedArticleContent.advancedTables.junctions.categories;
export const example_advanced_articles_related_articles =
  advancedArticleContent.advancedTables.junctions.relatedArticles;
```

</Step>

<Step>

### Group related fields [#group-related-fields]

`field.group` keeps fields that belong together under one key:

```ts title="plugins/example/src/content/advanced-article.ts"
syndication: field.group({
  fields: {
    indexable: field.boolean({ defaultValue: true }),
    noIndex: field.boolean({ defaultValue: false }),
    priority: field.number({ integer: true, min: 0, max: 10, defaultValue: 5 }),
  },
}),
```

A group adds one column per leaf to the main table: `syndicationIndexable`, `syndicationNoIndex` and `syndicationPriority`. The API reads and writes it as `{ syndication: { indexable, noIndex, priority } }`, and other options refer to a leaf by path, such as `indexes: [{ on: ["syndication.priority"] }]`. Leaves can be `text`, `textarea`, `number`, `boolean`, `enum` or `dateTime` fields. An optional group needs leaves that are nullable or have a default.

</Step>

<Step>

### Add repeatable rows [#add-repeatable-rows]

`field.repeatable` stores an ordered list of small rows, such as FAQ entries:

```ts title="plugins/example/src/content/advanced-article.ts"
faq: field.repeatable({
  max: 20,
  fields: {
    question: field.text({ required: true, minLength: 3, maxLength: 200 }),
    answer: field.textarea({ required: true }),
  },
}),
```

The rows go to a child table, `example_advanced_articles_faq`, with `id`, `itemId`, `position`, `createdAt`, `updatedAt` and one column per leaf. Deleting the article deletes its rows. Export the child table too:

```ts title="plugins/example/src/database/advanced-articles.ts"
export const example_advanced_articles_faq =
  advancedArticleContent.advancedTables.repeatables.faq;
```

</Step>

<Step>

### Build and migrate [#build-and-migrate]

```bash tab="bun"
bun run build:plugins && bun run db:migrate
```

```bash tab="pnpm"
pnpm build:plugins && pnpm db:migrate
```

```bash tab="npm"
npm run build:plugins && npm run db:migrate
```

</Tabs>

The generated migration creates one table per junction and repeatable field.

</Step>

</Steps>

## Relations across id strategies [#relations-across-id-strategies]

A relation can point at a content type with a different [`idStrategy`](/docs/content-engine/id-strategy). The foreign key always takes the type of the key it references. The example plugin's `example.event` uses `bigint` and links to `uuid` tags and `serial` categories:

```ts title="plugins/example/src/content/event.ts"
import type { ContentRelationTarget } from "@vitnode/core/content";

import { categoryContentType } from "./category";
import { tagContentType } from "./tag";

fields: {
  primaryTag: field.relation({
    nullable: true,
    onDelete: "set null",
    target: (): ContentRelationTarget<"uuid"> => tagContentType,
  }),
  category: field.relation({
    nullable: true,
    onDelete: "set null",
    target: () => categoryContentType,
  }),
  tags: field.relation({ multiple: true, ordered: true, target: () => tagContentType }),
  relatedEvents: field.relation({ multiple: true, onDelete: "cascade", self: true }),
},
```

| Field           | Column or junction table                                            |
| --------------- | ------------------------------------------------------------------- |
| `primaryTag`    | `uuid` column referencing `example_tags.id`                         |
| `category`      | `integer` column referencing `example_categories.id`                |
| `tags`          | `example_events_tags` with `itemId bigint` and `relatedItemId uuid` |
| `relatedEvents` | `example_events_related_events` with both columns `bigint`          |

`field.relation()` reads the target's strategy from `target`, so the API takes and returns tag ids as strings and category ids as numbers. When two content type modules import each other, TypeScript cannot infer a type through the cycle and falls back to serial. Annotate the thunk with `ContentRelationTarget<"uuid">` or `ContentRelationTarget<"bigint">`, as `primaryTag` does. At runtime, a `references` entry whose column type disagrees with the target's strategy throws and names the field.

## Write related values [#write-related-values]

A relation takes ids. A to-many relation and a repeatable take the whole list, which replaces what the record had:

```json
{
  "categories": [2, 4],
  "syndication": { "priority": 7 },
  "faq": [
    {
      "id": 1,
      "question": "Can I freeze the batter?",
      "answer": "Yes, for up to a month."
    },
    { "question": "Do I need buttermilk?", "answer": "No, regular milk works." }
  ]
}
```

A repeatable row with an `id` updates that row, a row without one is created, and rows you leave out are deleted. The API refuses an `id` that belongs to another record with `CONTENT_REPEATABLE_UNKNOWN_CHILD`. To change one link or one row without sending the list, use the [content service](/docs/content-engine/services): `relations.categories.add()`, `.remove()`, `.set()`, `.reorder()` and `.get()`, or `repeatable.faq.create()`, `.update()`, `.delete()`, `.reorder()`, `.set()` and `.list()`.

## Check the result [#check-the-result]

In the AdminCP form, a single relation is a search picker. This is the article's **Category** field:

A to-many relation shows each target as a chip you can remove. Here is the blog plugin's **Categories** field, a `field.relation({ multiple: true })`:

A group renders as a fieldset with its leaf controls, and a repeatable as a list of rows with move up, move down and remove buttons plus an **Add** button. The example plugin gives the advanced article API routes but no AdminCP screen, so test it through the API. Its public API returns the related values like this:

```bash
curl "http://localhost:3000/api/@vitnode/example/content/advanced-articles/weekend-pancakes?locale=en"
```

```json
{
  "id": 1,
  "title": "Weekend pancakes",
  "slug": "weekend-pancakes",
  "categories": [2, 4],
  "seo": {
    "title": "Fluffy weekend pancakes",
    "description": "Ready in 20 minutes."
  },
  "syndication": { "priority": 7, "noIndex": false },
  "faq": [
    {
      "id": 1,
      "question": "Can I freeze the batter?",
      "answer": "Yes, for up to a month."
    },
    {
      "id": 2,
      "question": "Do I need buttermilk?",
      "answer": "No, regular milk works."
    }
  ],
  "publishedAt": "2026-10-10T10:57:42.767Z",
  "locale": "en"
}
```

A to-many relation comes back as a list of ids, and a single relation as `{ "id": 2 }`. Only the leaves listed in `publicApi.fields`, such as `"faq.question"`, are public. The example plugin's page at `/advanced-articles/weekend-pancakes` renders the FAQ rows:

Every option of these helpers is in the [Fields](/docs/content-engine/fields#relation) reference.

# Rich text (/docs/content-engine/rich-text)

`field.richText()` is the Content Engine field for formatted text: headings, lists, links, tables, task lists and panels. Editors write it in the AdminCP with the Tiptap editor. Readers get plain HTML from `RichTextContent`, a small React component that never loads the editor, so the public page stays light. Your readers came for the article, not for an editor they will never type in.

## Define a rich text field [#define-a-rich-text-field]

Add the field to a content type. The blog plugin's article body is the typical case:

```ts title="plugins/blog/src/content/post.ts"
import { defineContentType, field } from "@vitnode/core/content";

export const blogPostContentType = defineContentType({
  id: "blog.post",
  tableName: "blog_posts",
  fields: {
    title: field.text({
      localized: true,
      required: true,
      minLength: 3,
      maxLength: 255,
    }),
    content: field.richText({ localized: true, required: true }), // [!code highlight]
  },
});
```

The excerpt leaves out the blog's `localization` block, which `localized: true` needs; see [Translations](/docs/content-engine/localization).

The column is `jsonb`, and the value is a ProseMirror document, the same JSON that Tiptap's `editor.getJSON()` returns:

```json
{
  "type": "doc",
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "Hello!" }] }
  ]
}
```

The Content Engine validates every write. The value must be a `doc`, nest at most 64 levels deep, and fit in `maxBytes` as UTF-8 JSON (1 MB by default, up to 16 MB). With `required: true`, a document without any text or media is refused, so an empty editor cannot be saved. A rich text field has no default, so set `required` or `nullable`.

The AdminCP form shows the editor for the field, and it loads the editor only when the form has a rich text field:

## Render it on a public page [#render-it-on-a-public-page]

Import `RichTextContent` from `@vitnode/core/components/rich-text` and pass the document. It works during SSR and in the browser. Validate the API response with `zodRichTextDocument`:

```tsx title="plugins/blog/src/pages/post-page.tsx"
import { RichTextContent } from "@vitnode/core/components/rich-text";
import { zodRichTextDocument } from "@vitnode/core/content";
import { z } from "zod";

const zodBlogPost = z.object({
  content: zodRichTextDocument,
  title: z.string(),
});

const BlogPostPage = ({ item }: { item: z.infer<typeof zodBlogPost> }) => (
  <article>
    <h1>{item.title}</h1>
    <RichTextContent
      className="text-foreground leading-relaxed text-pretty"
      content={item.content}
    />
  </article>
);
```

The output is wrapped in `<div class="tiptap">` and uses the same classes as the editor, such as `list-disc`, `tableWrapper` and `tiptap-panel`. Import `@vitnode/core/styles/tiptap.css` in your app stylesheet to style it, as `apps/web/src/styles.css` does.

`RichTextContent` treats the document as untrusted input:

- Links keep only `http:`, `https:`, `mailto:`, `tel:`, relative and `#` targets. A `javascript:` or `data:` link renders as plain text.
- Images and other media keep only `http:`, `https:` and relative sources.
- A link that opens a new tab gets `rel="noopener noreferrer nofollow"`.
- Inline styles come from an allowlist: text colors, font sizes with a unit and text alignment.
- An unknown node renders its children, and an unknown mark renders plain text.

## Replace a renderer [#replace-a-renderer]

Pass `nodes` or `marks` to change how one type renders. The keys are ProseMirror type names, and each renderer receives the node (or mark) and its already rendered children:

```tsx
<RichTextContent
  content={item.content}
  nodes={{
    heading: ({ children, node }) =>
      node.attrs?.level === 2 ? (
        <h2 className="scroll-mt-20">{children}</h2>
      ) : (
        <h3>{children}</h3>
      ),
  }}
/>
```

A custom renderer is your code, so the built-in link and style allowlists do not run for it. Check anything it reads from `attrs`; `sanitizeRichTextHref` from `@vitnode/core/components/rich-text` cleans a link.

## Get plain text or HTML [#get-plain-text-or-html]

Three helpers work on the server and in the browser without React. Import them from `@vitnode/core/content` or `@vitnode/core/components/rich-text`:

| Helper                     | Returns   | Use it for                                                               |
| -------------------------- | --------- | ------------------------------------------------------------------------ |
| `richTextToPlainText(doc)` | `string`  | Search, excerpts, AI prompts, word counts. One line per block, no markup |
| `richTextToHtml(doc)`      | `string`  | Emails and feeds. Escaped, with the same allowlists as `RichTextContent` |
| `isRichTextEmpty(doc)`     | `boolean` | Checking whether a document has any text or media                        |

```ts
import { richTextToPlainText } from "@vitnode/core/content";

const words = richTextToPlainText(post.content).split(/\s+/).length;
```

The Content Engine already uses them. Site search indexes the words of a rich text field listed in `search.contentFields`. A rich text field named in `delivery.seo.descriptionField` or `fallbackDescriptionField` becomes a plain text description, which is how the blog fills its meta description from `content` when an article has no excerpt. The revision history compares documents as text.

## Use the editor in your own form [#use-the-editor-in-your-own-form]

Outside the Content Engine, `AutoFormEditor` from `@vitnode/core/components/form/fields/editor` stores an HTML string by default. Add `format="json"` to store a ProseMirror document instead:

```tsx
<AutoFormEditor {...props} format="json" label="Body" />
```

The [Editor](/docs/ui/editor) page covers the component itself.

## Check the result [#check-the-result]

Open **AdminCP → Blog → Articles → Create Article**, write a heading and a list in **Content** and save. The public article shows the same structure, rendered by `RichTextContent` without loading Tiptap, ProseMirror or Yjs.

Several editors can type into the same rich text field at once; [Live editing](/docs/content-engine/live-editing) covers co-editing and presence.

# Search (/docs/content-engine/search)

Add a `search` block to a content type and its published records show up on the site search page at `/search`. VitNode writes a search document after every save, publish and delete, so you never call the search engine yourself. This guide turns search on for `example.article` from the example plugin.

## Before you begin [#before-you-begin]

The content type needs [publication and a public API](/docs/content-engine/public-api), because a search result is a link to a public page and its text has to be public already. Without them, the definition throws when it loads: ``search needs `publication: true`.`` or ``search needs `publicApi: { path, fields }`.``

It also needs a page that serves the result URL. [Public pages](/docs/content-engine/public-pages) shows how to add one.

<Steps>

<Step>

### Add the search block [#add-the-search-block]

Add `search` to the definition. This excerpt leaves out the fields and blocks search does not read:

```ts title="plugins/example/src/content/article.ts"
export const articleContentType = defineContentType({
  id: "example.article",
  tableName: "example_articles",
  fields: {
    title: field.text({ required: true, minLength: 3, maxLength: 200 }),
    slug: field.slug({ source: "title" }),
    excerpt: field.textarea({ maxLength: 500, nullable: true }),
    author: field.user(),
  },
  publication: true,
  publicApi: {
    path: "articles",
    fields: ["title", "slug", "excerpt", "publishedAt"],
  },
  // [!code ++:7]
  search: {
    titleField: "title",
    descriptionField: "excerpt",
    contentFields: ["title", "excerpt"],
    pathTemplate: "/articles/{slug}",
    authorField: "author",
  },
});
```

- `titleField` is the result heading. It must be a `field.text()` that is not nullable.
- `descriptionField` is optional and leads the result excerpt. Text, textarea or rich text.
- `contentFields` is the searchable body. It takes at least one field and no duplicates. Text, textarea, rich text or slug fields, plus repeatable leaves such as `"faq.answer"`. Rich text is indexed as its words, never as JSON. The title always ranks higher than the body, so listing it here as well only repeats it in the excerpt.
- `pathTemplate` is the result URL. It starts with `/` and contains `{slug}` exactly once. Leave the language out, because your i18n settings add it (see [Localized content types](#localized-content-types)).
- `authorField` is optional and credits a top-level `field.user()` on [member timelines](/docs/dev/search#member-timelines).
- `imageField` is optional and shows a `field.file()` image next to each result. See [Credit several authors and add an image](#credit-several-authors-and-add-an-image).

Every field except `authorField` must be in `publicApi.fields`. Otherwise a result snippet would leak a private value, so the definition throws instead: `search.titleField names "x", which is not in publicApi.fields.` `authorField` may stay private, which is why `author` is not in the public list above. All options are in the [reference](/docs/content-engine/reference#search).

</Step>

<Step>

### Index the records you already have [#index-the-records-you-already-have]

New writes are indexed from now on, but records saved before the `search` block existed are not. Open **AdminCP → Advanced → Search** (`/admin/core/advanced/search`), type `example.article` into **Search collections…**, and click **Reindex** on that row. **Rebuild index** at the top rebuilds every collection.

Both buttons need the **Rebuild and clear the search index** staff permission (`system` → `can_manage_search`). A rebuild clears the collection and refills it in pages of 200 records. It is a queued job, so it only runs while [cron](/docs/dev/cron) is running.

**Items** compares indexed documents with records in the table, drafts included. Content Engine collections are all labelled **Content** for now, so filter by the content type id to find yours.

</Step>

</Steps>

## Credit several authors and add an image [#credit-several-authors-and-add-an-image]

A result can show everyone who wrote the record and a picture of it, on `/search`, `/discover` and member timelines. The blog does both: an article lists all its authors and its cover image.

{/* Image prompt: A VitNode search result card in light theme. Top left, three small overlapping round avatars followed by "admin, devloop_tester and aXen · Aug 15, 4:14 PM". Below, a bold title "Hello Content Engine" and two lines of grey excerpt. On the right, a rounded 16:9 cover photo thumbnail. 1200x400. */}

Make the author field hold several users, add a single image field, and point `search` at both:

```ts title="plugins/blog/src/content/post.ts"
export const blogPostContentType = defineContentType({
  fields: {
    title: field.text({ required: true }),
    friendlyUrl: field.slug({ source: "title" }),
    content: field.richText(),
    // [!code ++:6]
    authorId: field.user({ min: 1, multiple: true, ordered: true }),
    coverImage: field.file({
      allowedExtensions: [".jpg", ".jpeg", ".png", ".webp", ".avif"],
      allowedMimeTypes: ["image/jpeg", "image/png", "image/webp", "image/avif"],
    }),
  },
  publication: true,
  publicApi: {
    path: "blog",
    fields: ["id", "title", "friendlyUrl", "content", "coverImage"], // [!code highlight]
  },
  search: {
    titleField: "title",
    contentFields: ["title", "content"],
    pathTemplate: "/blog/{slug}",
    // [!code ++:2]
    authorField: "authorId",
    imageField: "coverImage",
  },
});
```

- **Authors.** With `multiple: true`, every user in the field is credited, and `ordered: true` keeps the order you pick in the editor. A result shows up to three overlapping avatars and the names in that order, such as **admin, devloop_tester and aXen**. Past three it says **admin, devloop_tester and 2 others**. Every co-author gets the record on their own timeline.
- **Image.** `imageField` names one shared `field.file()`, not a list and not a localized field, and it must be in `publicApi.fields`, because everybody who finds the result sees it. It shows as a small 16:9 thumbnail on the right of the result, and full width above the text on phones. Records without an image show none, and a file that is not an image is skipped.

The definition throws when either one points at the wrong kind of field, for example `search.imageField names "gallery", which is not a shared single field.file() on the record itself.`

Adding `authorField` or `imageField` to content that already exists needs a **Reindex** of the collection, so older records pick them up. After that, changing the authors or the image re-indexes the record on save.

In the API, each result carries `authors` (id, name, `nameCode`, avatar) in order, `authorIds`, and `image` with `url`, `width` and `height`, or `null`.

## What gets indexed and when [#what-gets-indexed-and-when]

Every record is in the index, but only public ones show up on `/search`. A draft is stored as a private document without a URL. A [hidden](/docs/content-engine/content-visibility) record's document turns private the moment it is hidden, and public again when it is unhidden. With `authorField`, it appears on its author's own timeline and on the AdminCP user page, but never in public results.

| Write                                                                                       | Search index                  |
| ------------------------------------------------------------------------------------------- | ----------------------------- |
| Create, edit, publish, unpublish, restore, hide, unhide, duplicate or delete in the AdminCP | Updated right after the write |
| A scheduled publish or unpublish                                                            | Updated when the job runs     |
| Your own route using the editorial service and `contentEditorialEffects`                    | Updated                       |
| The plain `service` from `model.service(c)`                                                 | Not updated                   |

An edit rewrites the document only when an indexed field changed: the title, description, content fields, slug or author. Unpublishing keeps the document but makes it private, so the record drops out of `/search` at once. Deleting the record removes its document.

The plain service writes rows and nothing else. To change records from your own code and keep search in sync, follow [a "Feature this article" button](/docs/content-engine/services#example-3-a-feature-this-article-button).

If the search engine fails, the save still succeeds. The failure is logged with a `[content-search]` prefix and listed under **Recent sync failures** on the AdminCP Search screen. Reindex the collection to repair it.

## Localized content types [#localized-content-types]

A [localized](/docs/content-engine/localization) content type such as `example.localized-article` gets one document per translation, with the language stored on it. A translation is public only when both the record and that translation are published. Deleting a translation removes only that language's document. Deleting the record removes all of them.

`/search` shows documents in the visitor's language. Documents of content types that are not localized match every language. With `localization.fallback: "default"`, a visitor whose language has no published translation sees the default language's document instead.

Each document gets the URL of its own language. `pathTemplate` stays the English route, and VitNode adds the prefix, domain and translated segments from your [localized URL settings](/docs/dev/i18n/localized-urls). The table in [Result URLs for Content Engine types](/docs/dev/search#result-urls-for-content-engine-types) shows what each setting produces. URLs are stored at indexing time, so reindex after changing `pathTemplate` or those settings.

## Check the result [#check-the-result]

1. Publish an article in **AdminCP → Example → Articles**.
2. Open `/search` and type a whole word or two from its title or excerpt. The result links to `/articles/{slug}`.

The same results come from the public search API. `types` limits them to one content type:

```bash
curl "http://localhost:3000/api/@vitnode/core/search?search=hello&types=example.article"
```

```json
{
  "edges": [
    {
      "pluginId": "@vitnode/example",
      "itemType": "example.article",
      "itemId": 3,
      "languageCode": "",
      "title": "Hello Content Engine",
      "content": "Hello Content Engine A first article from the example plugin, served by the public API and rendered on its own page.",
      "url": "/articles/hello-content-engine",
      "isPublic": true
    }
  ]
}
```

Unpublish the article and run the request again. This time `edges` is empty. If a record you published before adding `search` is missing, reindex the collection.

The index runs on Postgres full-text search by default. To switch engines, or to index data that is not a content type, see [Search & Discovery](/docs/dev/search) and [Elasticsearch](/docs/dev/search-elasticsearch).

# SEO (/docs/content-engine/seo)

Once a content type has [public pages](/docs/content-engine/public-pages), `delivery.seo` decides which fields fill each page's `<title>`, meta description and `robots` tag, and `delivery.sitemap` lists the pages for crawlers. You name fields; the Content Engine reads them from every published record, so editors never fill in a separate SEO form unless you give them one.

The examples use `example.article` from the example plugin and `blog.post` from the blog plugin, which is localized.

## Pick the SEO fields [#pick-the-seo-fields]

`example.article` uses its title and excerpt, plus a boolean that hides a record from search engines:

```ts title="plugins/example/src/content/article.ts"
fields: {
  title: field.text({ required: true, minLength: 3, maxLength: 200 }),
  excerpt: field.textarea({ maxLength: 500, nullable: true }),
  noIndex: field.boolean({ nullable: true }),
},

publicApi: {
  path: "articles",
  fields: ["title", "slug", "excerpt", "noIndex", "publishedAt"],
},

delivery: {
  redirects: true,
  seo: {
    titleField: "title",
    descriptionField: "excerpt",
    noIndexField: "noIndex",
    openGraph: { titleField: "title", descriptionField: "excerpt" },
  },
  sitemap: { changeFrequency: "weekly", priority: 0.7 },
},
```

| Option                           | Field kinds              | Used for                                                     |
| -------------------------------- | ------------------------ | ------------------------------------------------------------ |
| `titleField`                     | text                     | Page title                                                   |
| `fallbackTitleField`             | text                     | Page title when `titleField` is empty. Needs `titleField`    |
| `descriptionField`               | text, textarea, richText | Meta description                                             |
| `fallbackDescriptionField`       | text, textarea, richText | Description when `descriptionField` is empty                 |
| `noIndexField`                   | boolean, not localized   | `robots` tag and sitemap, see [noindex](#hide-a-record-from-search-engines) |
| `openGraph.titleField`           | text                     | Open Graph title, falls back to the page title               |
| `openGraph.descriptionField`     | text, textarea, richText | Open Graph description, falls back to the page description   |

Every field you name must also be in `publicApi.fields`, because the page shows it to anyone. Leave one out and the definition throws at startup with `... which is not in publicApi.fields`. A field inside a group works (`"seo.title"`). A field inside a repeatable does not, since a page has one title, not a list of them.

Values are trimmed, and an empty one counts as missing, so the fallback kicks in. The blog uses that to describe posts that have no excerpt:

```ts title="plugins/blog/src/content/post.ts"
delivery: {
  seo: {
    titleField: "title",
    descriptionField: "excerpt",
    fallbackDescriptionField: "content",
  },
},
```

`content` is rich text. The Content Engine turns it into plain text, and the page cuts it to 160 characters at a word boundary and adds `…`. No markup ever lands in a meta tag.

The blog plugin's own article editor checks the fields this rule reads in its **SEO** sheet. The sheet belongs to the blog plugin, not to every Content Engine form. Here the post has no excerpt, so the **Excerpt** row is marked as missing, and search results would fall back to the content.

## What reaches the page head [#what-reaches-the-page-head]

The page's `head` calls `contentDeliveryPageHead` with the resolve route's answer, as shown in [Write the page](/docs/content-engine/public-pages#write-the-page). This is what the HTML gets today:

| Tag                                         | Rendered                                    |
| ------------------------------------------- | ------------------------------------------- |
| `<title>`                                   | Yes, followed by the site title (`- VitNode`) |
| `<meta name="description">`                 | Yes, at most 160 characters                 |
| `<meta name="robots">`                      | Only for a no-index record                  |
| `<link rel="canonical">` and `hreflang` links | Only for a localized content type         |
| `og:title`, `og:description`                | No                                          |

<Callout type="warn">
  The resolve route returns `openGraph` and `canonicalPath` for every record, but nothing turns them into tags yet. A nonlocalized type such as `example.article` gets no canonical link, and no content type gets Open Graph tags. A plugin page cannot add them either, because its `head` only accepts `title`, `description`, `robots` and `alternates`. Keep `openGraph` in your definition so the data is ready, and read it from the resolve route if you render pages outside VitNode.
</Callout>

## Hide a record from search engines [#hide-a-record-from-search-engines]

`noIndexField` names one boolean that drives two things together:

- the page gets `<meta content="noindex, nofollow" name="robots"/>`;
- the record leaves the [sitemap](#sitemap).

Only `true` hides a record. `null` and `false` both mean "index it", which is why `example.article` can make the field nullable without emptying its sitemap. The resolve route reports the decision as `"robots": { "follow": true, "index": false }`.

The field must be shared, not localized. A record has one indexing decision, and a per-language value would let the Polish page say `noindex` while the sitemap lists the English one. The definition refuses a localized `noIndexField` for that reason.

## Localized alternates and hreflang [#localized-alternates-and-hreflang]

For a [localized](/docs/content-engine/localization) content type, the page head links every published translation of the record. The blog post `english-title` is published in English and Polish, so `/blog/english-title` gets:

```html
<link href="http://localhost:3000/blog/english-title" rel="canonical"/>
<link href="http://localhost:3000/blog/english-title" hrefLang="en" rel="alternate"/>
<link href="http://localhost:3000/pl/wpisy/polish-title" hrefLang="pl" rel="alternate"/>
<link href="http://localhost:3000/blog/english-title" hrefLang="x-default" rel="alternate"/>
```

- The canonical link is the page's own language.
- Each URL follows the app's [localized URL rules](/docs/dev/i18n/localized-urls), which is how the Polish post ends up at `/pl/wpisy/...`.
- Links are absolute, built from `VITNODE_WEB_URL` (`http://localhost:3000` when unset) unless a language has its own domain.
- A translation that is not published is not an alternate.
- Delivery on a localized type needs `"id"` in `publicApi.fields`, because alternates are looked up by record id. The definition throws without it.

`hreflang: { xDefault: "defaultLocale" }` adds `hreflang.xDefault` to the resolve route's answer, pointing at the record's default-language URL when that translation is published. It needs `localization`. The page head does not read this option. It adds its `x-default` link whenever the app's default language is among the alternates, with or without it, so the option only matters when you read the resolve route yourself.

```ts title="plugins/blog/src/content/post.ts"
delivery: {
  hreflang: { xDefault: "defaultLocale" },
},
```

## Sitemap [#sitemap]

`delivery.sitemap` adds a public route that lists every published URL of the content type, oldest record first. Pass `true` or `{ changeFrequency, priority }`. It needs `publication: true`, since a sitemap lists only what readers can reach.

```bash
curl "http://localhost:3000/api/@vitnode/example/content/articles/delivery/sitemap?cursor=1&limit=1"
```

```json
{
  "entries": [
    {
      "changeFrequency": "weekly",
      "itemId": 3,
      "lastModified": "2026-10-10T11:06:30.518Z",
      "locale": null,
      "path": "/articles/hello-content-engine",
      "priority": 0.7
    }
  ],
  "nextCursor": null
}
```

- A page holds 1,000 entries by default and up to 50,000 with `?limit=`. `cursor` is the `itemId` to continue after, so pass `nextCursor` back as `?cursor=` until it is `null`.
- `lastModified` is the record's `updatedAt`, or the translation's when that is newer.
- Records whose `noIndexField` is `true` are left out, and so are [hidden](/docs/content-engine/content-visibility) records.
- Entries come in id order. For a [uuid](/docs/content-engine/id-strategy) content type that order is lexical, not creation order, and every record still appears once.
- A localized type returns one language per request. Ask for another with `?locale=`:

```bash
curl "http://localhost:3000/api/@vitnode/blog/content/blog/delivery/sitemap?locale=pl&limit=1"
```

```json
{
  "entries": [
    {
      "changeFrequency": "weekly",
      "itemId": 4,
      "lastModified": "2026-08-12T18:00:43.308Z",
      "locale": "pl",
      "path": "/pl/wpisy/polish-title",
      "priority": 0.7
    }
  ],
  "nextCursor": 4
}
```

The app's `/sitemap.xml` does not read these routes for you, so add the entries where you build it. `contentSitemapXml` from `@vitnode/core/content` writes the XML:

```ts
import {
  contentSitemapXml,
  isContentSitemapChangeFrequency,
} from "@vitnode/core/content";

const response = await fetch(
  "http://localhost:3000/api/@vitnode/example/content/articles/delivery/sitemap",
);
const { entries } = await response.json();

const xml = contentSitemapXml({
  origin: "https://example.com",
  entries: entries.map(entry => ({
    ...entry,
    changeFrequency: isContentSitemapChangeFrequency(entry.changeFrequency)
      ? entry.changeFrequency
      : null,
    lastModified: new Date(entry.lastModified),
  })),
});
```

With the example plugin's two published articles, `xml` is:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/articles/jbbjk-1</loc>
    <lastmod>2026-08-30T09:18:25.398Z</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.7</priority>
  </url>
  <url>
    <loc>https://example.com/articles/hello-content-engine</loc>
    <lastmod>2026-10-10T11:06:30.518Z</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.7</priority>
  </url>
</urlset>
```

`contentSitemapIndexXml` writes a `<sitemapindex>` once one file is not enough, for example one file per content type and language.

## Retired slugs [#retired-slugs]

With `delivery.redirects`, an old slug answers a permanent `308` redirect to the record's current URL, so links and search results that still use the old address land on the new page. See [Keep old URLs working](/docs/content-engine/public-pages#keep-old-urls-working).

## Check the result [#check-the-result]

Print the SEO tags of an article and of a localized blog post:

```html
<title>Hello Content Engine - VitNode</title>
<meta content="A first article from the example plugin, served by the public API and rendered on its own page." name="description"/>
```

Run the same command for `http://localhost:3000/blog/english-title` and you get its title, description and the four links from [Localized alternates](#localized-alternates-and-hreflang). The SVG logo's `<title>Logo VitNode</title>` may show up too; it is not page metadata.

Then ask the resolve route what the page was given, `openGraph` and `robots` included:

```bash
curl http://localhost:3000/api/@vitnode/example/content/articles/delivery/resolve/hello-content-engine
```

Set `noIndex` on a test article, publish it, and run both commands again. The page gains the `robots` tag, and the [sitemap](#sitemap) route stops listing it.

# Services (/docs/content-engine/services)

The Content Engine already generates routes for creating, reading, updating, deleting and publishing records. A **service** is what you use when you need something those routes don't do, such as "the three newest articles in one category" or "create an article from a cron job". It is a typed object with methods like `findMany`, `create` and `publish`, and you get it from the model `createContentModel` returns.

Every example on this page uses the example plugin's article model:

```ts title="plugins/example/src/database/articles.ts"
import { createContentModel } from "@vitnode/core/content/server";

import { articleContentType } from "@/content/article";

import { example_categories } from "./categories";

export const articleContent = createContentModel(articleContentType, {
  references: { category: () => example_categories.id },
});
```

## The short version [#the-short-version]

Inside any Hono handler, call a service with the request context `c`:

```ts
const article = await articleContent.service(c).findById(1);
```

`article` is fully typed: `article.title` is a `string`, `article.featured` is a `boolean`, and a typo is a compile error. There are three services, and the only question is which one fits your task:

| You want to                                                  | Use                                        |
| ------------------------------------------------------------ | ------------------------------------------ |
| Show content to visitors: published records, public fields   | `articleContent.publicService(c)`          |
| Read or write anything, in a staff route, cron job or script | `articleContent.service(c)`                |
| Save a change the way the AdminCP does, with history         | `articleContent.editorialService(c, opts)` |

The three sections below build one real example for each.

## Example 1: the newest articles in a category [#example-1-the-newest-articles-in-a-category]

**Goal:** a public endpoint, `GET /api/@vitnode/example/articles/by-category/1`, that returns the three newest published articles in category `1`. Drafts must never appear, and neither may private fields.

`publicService` guarantees exactly that. It returns what the [public API](/docs/content-engine/public-api) would, so you cannot leak a draft by accident.

### Write the route [#write-the-route]

```ts title="plugins/example/src/api/modules/articles/by-category.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route";
import { z } from "zod";

import { CONFIG_PLUGIN } from "@/const";
import { articleContent } from "@/database/articles";

export const articlesByCategoryRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: {
    method: "get",
    path: "/by-category/{categoryId}",
    description: "Published articles in one category, newest first",
    request: {
      params: z.object({ categoryId: z.coerce.number().int().positive() }),
    },
    responses: {
      200: {
        content: {
          "application/json": {
            schema: z.array(
              z.object({
                publishedAt: z.date().nullable(),
                slug: z.string(),
                title: z.string(),
              }),
            ),
          },
        },
        description: "Up to three articles",
      },
    },
  },
  handler: async c => {
    const { publicService } = articleContent;
    if (!publicService) throw new Error("Articles have no public API.");

const { categoryId } = c.req.valid("param");
    const { edges } = await publicService(c).findMany({
      filters: { category: categoryId },
      orderBy: { column: "publishedAt", order: "desc" },
      query: { first: "3" },
    });

return c.json(
      edges.map(({ publishedAt, slug, title }) => ({
        publishedAt,
        slug,
        title,
      })),
      200,
    );
  },
});
```

The handler does three things:

1. **Gets the service.** `publicService` is `undefined` for a content type without `publicApi`, so the `if` makes that explicit once.
2. **Asks for records.** `filters` keeps only category `1`, `orderBy` puts the newest first and `query.first` limits it to three. `query` takes the same strings as the URL of a list route, which is why `first` is `"3"` and not `3`.
3. **Shapes the answer.** `edges` is the list of records. The route picks three fields so the response stays small.

`filters` only accepts fields listed in `publicApi.filterableFields`, and `orderBy.column` only fields in `publicApi.orderableFields`. Asking for anything else is a type error.

</Step>
<Step>

### Register it [#register-it]

Put the route in a module and add the module to your API plugin:

```ts title="plugins/example/src/api/modules/articles/articles.module.ts"
import { buildModule } from "@vitnode/core/api/lib/module";

import { CONFIG_PLUGIN } from "@/const";

import { articlesByCategoryRoute } from "./by-category.route";

export const articlesModule = buildModule({
  pluginId: CONFIG_PLUGIN.pluginId,
  name: "articles",
  routes: [articlesByCategoryRoute],
});
```

```ts title="plugins/example/src/config.api.ts"
modules: [adminModule, articlesModule],
```

</Step>
<Step>

### Call it [#call-it]

```bash
curl http://localhost:8000/api/@vitnode/example/articles/by-category/1
```

```json
[
  {
    "publishedAt": "2026-08-03T08:47:00.000Z",
    "slug": "jbbjk-1",
    "title": "old article, example"
  }
]
```

A category with no published articles answers `[]`. A draft in category `1` is not in the list, even though it exists.

</Step>
</Steps>

Need one record instead of a list? `publicService(c).findBySlug("jbbjk-1")` and `findById(1)` return one published record, or `null`.

## Example 2: create and publish an article from a job [#example-2-create-and-publish-an-article-from-a-job]

**Goal:** a [cron job](/docs/dev/cron) that publishes a "Weekly digest" article every Monday at 8:00.

There is no visitor and no staff member here, so you want the plain `service`. It sees every record and every field, including drafts, and it checks no permissions. That makes it the right tool for jobs and scripts, and the wrong one for a public route.

```ts title="plugins/example/src/api/cron/weekly-digest.cron.ts"
import { buildCron } from "@vitnode/core/api/lib/cron";

import { articleContent } from "@/database/articles";

export const weeklyDigestCron = buildCron({
  name: "weekly-digest",
  description: "Publish the weekly digest article",
  schedule: "0 8 * * 1",
  handler: async c => {
    const service = articleContent.service(c);

const article = await service.create({
      title: "Weekly digest",
      code: `digest-${Date.now()}`,
      category: 1,
      gallery: [21],
    });

await service.publish(article.id);
  },
});
```

Add it to a module's `cronJobs`, for example `cronJobs: [weeklyDigestCron]` in the `articles` module from Example 1.

`create` checks the values against the same rules as the AdminCP form: `title` is required and at least 3 characters, `gallery` needs at least one image, and so on. Values that break a rule throw a `ZodError` before anything is written. `slug` is filled from the title automatically.

To make several writes succeed or fail together, run them in one transaction by passing `{ tx }` as the last argument:

```ts
await c.get("db").transaction(async tx => {
  const article = await service.create(
    { title: "Weekly digest", code: "digest-41", category: 1, gallery: [21] },
    { tx },
  );
  await service.publish(article.id, { tx });
});
```

<Callout type="warn">
  The plain service is quiet. It emits no [events](/docs/content-engine/events),
  writes no revisions and does not update the search index. If a listener or
  the site search should notice the change, use the editorial service from
  Example 3.
</Callout>

## Example 3: a "Feature this article" button [#example-3-a-feature-this-article-button]

**Goal:** a staff endpoint, `POST /articles/1/feature`, that marks an article as featured, exactly as if someone had ticked **Featured** in the AdminCP and pressed **Save**. That means a revision in the history, the `updated` event, a search index update and protection against overwriting someone else's save.

That is the `editorialService` (available with [`editorial`](/docs/content-engine/editorial)). It needs one extra input, `expectedVersion`: the version of the article the button's page loaded. If somebody saved the article in the meantime, the versions differ and the request fails with `409` instead of silently overwriting their work.

```ts title="plugins/example/src/api/modules/admin/routes/feature.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route";
import {
  contentEditorialEffects,
  resolveContentActor,
  withHttpErrors,
} from "@vitnode/core/content/server";
import { HTTPException } from "hono/http-exception";
import { z } from "zod";

import { CONFIG_PLUGIN } from "@/const";
import { articleContent } from "@/database/articles";

export const featureArticleRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  adminStaffPermission: { module: "article", permission: "can_edit" },
  route: {
    method: "post",
    path: "/articles/{id}/feature",
    description: "Mark an article as featured",
    request: {
      params: z.object({ id: z.coerce.number().int().positive() }),
      body: {
        required: true,
        content: {
          "application/json": {
            schema: z.object({ expectedVersion: z.number().int().positive() }),
          },
        },
      },
    },
    responses: {
      200: {
        content: {
          "application/json": { schema: articleContent.schemas.select },
        },
        description: "The featured article",
      },
      404: { description: "Article not found" },
      409: { description: "Someone saved the article first" },
    },
  },
  handler: async c => {
    const { editorialService } = articleContent;
    if (!editorialService) throw new Error("Articles have no editorial.");

const { id } = c.req.valid("param");
    const { expectedVersion } = c.req.valid("json");
    const pluginId = CONFIG_PLUGIN.pluginId;

const outcome = await withHttpErrors(
      "update",
      async () =>
        await editorialService(c, { pluginId }).update(
          id,
          { featured: true },
          { actor: resolveContentActor(c), expectedVersion },
        ),
      {
        contentTypeId: articleContent.definition.id,
        itemId: id,
        structured: true,
      },
    );
    if (!outcome) throw new HTTPException(404);

await contentEditorialEffects(c, articleContent.definition, outcome, {
      model: articleContent,
      pluginId,
    });

return c.json(outcome.row, 200);
  },
});
```

Reading the handler top to bottom:

1. **`adminStaffPermission`** lets in only staff who may edit articles, the same check as the AdminCP's own edit route. Put the route in your plugin's `admin` module.
2. **`editorialService(...).update`** saves `featured: true` and writes a revision. `resolveContentActor(c)` puts the signed-in staff member's name on that revision.
3. **`withHttpErrors`** turns a version mismatch into a `409` response the AdminCP understands, instead of a crash.
4. **`contentEditorialEffects`** does everything that should happen after a save: it emits `content.example.article.updated`, updates the search index and handles URL changes. Skip it and the save is still stored, but nothing else hears about it.

The route lives in the `admin` module, so it answers at `POST /api/@vitnode/example/admin/articles/1/feature` and only to a signed-in AdminCP session. The body carries the version the page loaded:

```json
{ "expectedVersion": 3 }
```

If someone saved the article after version 3 was loaded, the answer is a `409`:

```json
{
  "code": "CONTENT_VERSION_CONFLICT",
  "contentTypeId": "example.article",
  "currentVersion": 4,
  "expectedVersion": 3,
  "itemId": 1
}
```

Load the article again, take the new version, and retry. A job without a signed-in user passes `CONTENT_SYSTEM_ACTOR` instead of `resolveContentActor(c)`.

## Hide, duplicate and content IDs [#hide-duplicate-and-content-ids]

A content type with [`visibility`](/docs/content-engine/content-visibility) or [`duplication`](/docs/content-engine/duplicate-content) adds methods to `service` and `editorialService`. They exist in the types only when the option is on, so calling `hide` on a content type without visibility is a compile error.

| Method                                     | `service` options                    | `editorialService` options                  |
| ------------------------------------------ | ------------------------------------ | ------------------------------------------- |
| `hide(id, options)`, `unhide(id, options)` | `{ actorUserId?, tx? }`              | `{ actor, expectedVersion?, tx? }`          |
| `duplicate(sourceId, options)`             | `{ overrides?, translations?, tx? }` | `{ actor, overrides?, translations?, tx? }` |

Hiding a record that is already hidden returns `changed: false` and writes nothing. The editorial `hide` and `unhide` raise the version and store a revision, and the editorial `duplicate` stores a first revision for the copy and for each copied translation. All of them return `null` when the record does not exist.

Like the other service methods, these emit no events. Run the effects after the transaction commits, as the generated routes do:

```ts
import { contentVisibilityEffects, resolveContentActor } from "@vitnode/core/content/server";

const { editorialService } = postContent;
if (!editorialService) throw new Error("Articles have no editorial.");

const pluginId = CONFIG_PLUGIN.pluginId;
const outcome = await editorialService(c, { pluginId }).hide(703, {
  actor: resolveContentActor(c),
});

if (outcome) {
  await contentVisibilityEffects(c, postContent, outcome, { pluginId });
}
```

`contentVisibilityEffects` emits `hidden` or `unhidden`, updates the search index and the delivery data, and [notifies front ends](/docs/content-engine/caching#notify-a-separate-front-end). It does nothing for an outcome with `changed: false`. For a copy, call `contentDuplicateEffects`, shown in [Duplicate content](/docs/content-engine/duplicate-content#duplicate-from-your-own-code).

### Content IDs [#content-ids]

Service methods take and return ids typed by the content type's [`idStrategy`](/docs/content-engine/id-strategy): `ContentIdOf<typeof articleContentType>` is `number` for a serial type and `string` for a uuid or bigint one. Never pass an id through `Number()` in code that may meet a bigint type.

A custom route reads an id from the URL as text. Parse it with the content type's strategy before calling a service, so a malformed id answers `400` instead of reaching the database. The example plugin's events use bigint ids:

```ts title="plugins/example/src/api/modules/events/title.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route";
import { parseContentIdOf } from "@vitnode/core/content";
import { HTTPException } from "hono/http-exception";
import { z } from "zod";

import { CONFIG_PLUGIN } from "@/const";
import { eventContentType } from "@/content/event";
import { eventContent } from "@/database/events";

export const eventTitleRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: {
    method: "get",
    path: "/{id}/title",
    description: "The title of one published event",
    responses: {
      200: {
        content: {
          "application/json": {
            schema: z.object({ id: z.string(), title: z.string() }),
          },
        },
        description: "The event title",
      },
      400: { description: "Invalid event id" },
      404: { description: "Event not found" },
    },
  },
  handler: async c => {
    const id = parseContentIdOf(eventContentType, c.req.param("id"));
    if (id === null) {
      throw new HTTPException(400, { message: "Invalid event id." });
    }

const { publicService } = eventContent;
    if (!publicService) throw new Error("Events have no public API.");

const event = await publicService(c).findById(id);
    if (!event) throw new HTTPException(404, { message: "Event not found." });

return c.json({ id, title: event.title }, 200);
  },
});
```

`id` is a `string` here, because `example.event` uses bigint. For a route that validates its parameters with Zod, `contentIdParamSchema(eventContentType.idStrategy)` accepts exactly what `parseContentIdOf` accepts. Code that handles content types it does not know statically uses `ContentId` (`number | string`) and `contentAnyIdSchema`. Every helper is listed in [Record ID strategies](/docs/content-engine/id-strategy#helpers).

## Reference [#reference]

### Service methods [#service-methods]

`publicService` only reads: `findMany({ filters, orderBy, query })`, `findById(id)` and `findBySlug(slug)`, each limited to published records and public fields. `editorialService` only writes: `create`, `update`, `delete`, `publish`, `unpublish`, `restore`, plus `relations` and `repeatable`, and `hide`, `unhide` and `duplicate` when their option is on. `service` has everything below:

| Method                                         | Returns                                                                               |
| ---------------------------------------------- | ------------------------------------------------------------------------------------- |
| `findMany({ filters, orderBy, query, where })` | `{ edges, pageInfo }`, drafts included. `where` takes a Drizzle `SQL` condition       |
| `findById(id)`                                 | The row, or `null`                                                                    |
| `findRowById(id)`                              | The row with display labels for relations and users, or `null`                        |
| `findDetail(id)`                               | The row with relation, repeatable and file values, or `null`                          |
| `create(values)`                               | The new row                                                                           |
| `update(id, values)`                           | `{ row, changedFields }`, or `null` when the id does not exist                        |
| `delete(id)`                                   | The deleted row, or `null`                                                            |
| `publish(id)`, `unpublish(id)`                 | `{ changed, publishedAt, row }`, or `null`. Only with `publication`                   |
| `hide(id)`, `unhide(id)`                       | `{ changed, hiddenAt, hiddenBy, row }`, or `null`. Only with `visibility`             |
| `duplicate(sourceId)`                          | `{ row, sourceId, translations, skippedLocales }`, or `null`. Only with `duplication` |
| `advanced(id)`, `advancedFields(id, fields)`   | Values of to-many relations, repeatables and galleries                           |
| `options(field, search?, ids?)`                | `{ value, label, color? }[]` for a relation or user picker                       |
| `relations.<field>`                            | `add`, `remove`, `set`, `reorder`, `get` for a to-many relation                  |
| `repeatable.<field>`                           | `create`, `update`, `delete`, `reorder`, `set`, `list` for a repeatable          |

On `service`, every write and every single-record read accepts `{ tx }` as its last argument. On `editorialService`, every write takes an options object with `actor`; `update`, `delete` and `restore` also take `expectedVersion`, which `publish` and `unpublish` treat as optional. A [localized](/docs/content-engine/localization) content type also has `localizedService` for writing translations.

### Schemas [#schemas]

`articleContent.schemas` holds the Zod schemas the generated routes validate with. Reuse them so a custom route accepts and returns exactly what the built-in ones do, as Example 3 does with `select`:

| Schema                               | Validates                                                      |
| ------------------------------------ | -------------------------------------------------------------- |
| `create`                             | A create payload, with required fields and defaults            |
| `update`                             | A partial update payload, never empty                          |
| `updateEnvelope`                     | `{ expectedVersion, values }` for an editorial update          |
| `select`, `selectObject`             | A full row (`selectObject` stays a `ZodObject` you can extend) |
| `publicSelect`, `publicSelectObject` | A row as the public API returns it                             |
| `filters`, `publicFilters`           | Staff and public list filters                                  |
| `order`, `publicOrder`               | The `orderBy` allowlist plus direction                         |
| `params`, `publicParams`             | `{ id }` and `{ slug }` path parameters                        |
| `form`                               | The AdminCP form values                                        |

To react to writes instead of making them, see [Events](/docs/content-engine/events).

# Authorization & Sessions (/docs/dev/advanced/auth)

VitNode implements two isolated sessions: a **public session** for the community site and a separate **admin session** for the AdminCP. Both use opaque random tokens stored as SHA-256 hashes in PostgreSQL.

## Quick start [#quick-start]

Customize session parameters in `apps/api/src/vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:6]
  authorization: {
    cookieExpires: 1000 * 60 * 60 * 24 * 30, // 30 days for public users
    adminCookieExpires: 1000 * 60 * 30, // sign staff out after 30 idle minutes
    cookieDomain: ".yourdomain.com", // Optional cross-subdomain sharing
  },
})
```

---

## The Two-Session Model [#the-two-session-model]

<Callout type="info" title="Session Isolation">
  Signing out of the AdminCP does not terminate the user's public session, and vice versa. An administrator compromised in a public context cannot access the AdminCP without re-authenticating with staff credentials - a password or a user-verified passkey, checked against live staff access. Neither a public session nor social SSO ever becomes an AdminCP session.
</Callout>

---

## AdminCP Session Timeout [#admincp-session-timeout]

The AdminCP is the keys to the kingdom, so its session is deliberately short-lived. Staff are asked to sign in again when:

- **They go quiet for an hour.** Every AdminCP request pushes the expiry an hour ahead, so an admin who keeps working is never interrupted. Leave the tab alone for an hour and it signs itself out and lands on the sign-in page, with a toast explaining why. Tune the window with `adminCookieExpires`.
- **They close every AdminCP tab.** Open AdminCP tabs keep a heartbeat going. Open the AdminCP again after every tab was closed and VitNode ends the old session instead of letting it back in. A page reload, or opening one more AdminCP tab while another is still open, is not affected. This check is skipped when `cookieDomain` is set: a browser can only see tabs on its own origin, so an AdminCP tab open on another subdomain would look closed.
- **They close the browser.** The `vitnode_auth_admin` cookie has no expiry date, so the browser drops it when it shuts down.

<Callout type="info" title="Leaving the AdminCP counts as closing it">
  Moving from the AdminCP to the public site in your only AdminCP tab stops the heartbeat. Come back within about 15 seconds and you are still signed in; any later and you sign in again. Open the public site in a new tab to keep your AdminCP session.
</Callout>

---

## Security Guarantees [#security-guarantees]

- **SHA-256 Token Storage**: The raw token is stored only in the user's `HttpOnly` cookie. The database stores only its cryptographic hash. Sign-in, SSO and passkey answers carry the user id only - page scripts never see the token.
- **Device Pinning**: Tokens are bound to a verified device ID. Tokens copied to another device without the matching device cookie are rejected.
- **Fast 60-Second Caching**: Active sessions are cached in Redis for up to 60 seconds, eliminating database query overhead on repeated requests.
- **Confirmed Email Addresses**: With an email adapter, members confirm their address before their first sign-in. See [Email Verification](/docs/dev/working-with-users/email-verification).
- **Canonical Email Identity**: Addresses are stored in their canonical form, so Gmail dot, `googlemail.com` and `+tag` variants cannot become a second account. See [One Mailbox, One Account](#one-mailbox-one-account).

---

## One Mailbox, One Account [#one-mailbox-one-account]

`jankowalski@gmail.com` and `jan.kowalski@gmail.com` look like two addresses. Gmail ignores the dots, so they are one mailbox - and a site that treats them as two lets the same person hold two accounts, dodge a ban, or farm their own referral link.

VitNode stores the **canonical** form of an address, so those tricks collapse into a single account:

The rules are per-provider, because they are only true per-provider:

- **Dots are removed for `gmail.com` and `googlemail.com` only.** Everywhere else a dot is part of the mailbox, so `jan.kowalski@company.com` is left alone.
- **`googlemail.com` folds into `gmail.com`.** Google treats them as one domain.
- **`+tag` suffixes are dropped** for Gmail and for the providers that document sub-addressing: Outlook, Hotmail, Live, MSN, iCloud, Proton, Fastmail, GMX, Yandex and Zoho. Mail sent to the canonical address still lands in the same inbox.
- **Everything else is kept as typed**, lowercased. A `+` can be a real character in a corporate address, so guessing there would lock people out.
- **Yahoo's `-` aliases are deliberately left alone**, because `jan-kowalski@yahoo.com` is a perfectly ordinary name.

<Callout type="info" title="Where it applies">
  Sign-up, sign-in, password reset, the SSO callback and AdminCP user management all resolve an address the same way. Someone who registered with a password at `jankowalski@gmail.com` and later clicks *Sign in with Google* - which hands back `jan.kowalski@gmail.com` - lands on their own account instead of a second one.
</Callout>

<Callout type="warn" title="Upgrading an existing install">
  The `20260906174535_canonicalize_user_emails` migration rewrites stored addresses in place. A row whose canonical form is already taken by another row is left untouched, so nobody is locked out and no two accounts are silently merged. Run this before upgrading to see whether your install has such pairs:

```sql
  SELECT
    replace(split_part(split_part(lower("email"), '@', 1), '+', 1), '.', '') AS mailbox,
    array_agg("email")
  FROM "core_users"
  WHERE lower("email") LIKE '%@gmail.com' OR lower("email") LIKE '%@googlemail.com'
  GROUP BY 1
  HAVING count(*) > 1;
  ```
</Callout>

## `authorization` Options Reference [#authorization-options-reference]

## Turning off password sign-in [#turning-off-password-sign-in]

Running a passkeys-only or social-login-only community? Switch passwords off:

```ts title="apps/api/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:3]
  authorization: {
    password: false,
  },
})
```

With passwords off:

- `/login` hides the email + password form and **Forgot password?**. It keeps [SSO](/docs/dev/sso) buttons and **Sign in with a passkey** - if neither is configured, members see a "Signing in is unavailable" notice.
- `/register` hides the sign-up form. New accounts can still come in through SSO; with no SSO provider, the page says registration is unavailable and the "Sign up" link on `/login` goes away.
- `/login/reset-password` answers "not found".
- The API refuses `POST /users/sign_in` (for members), `/users/sign_up`, `/users/reset-password`, `/users/change-password` and password-based SSO linking with `403`.
- A stored password no longer counts as a way into the account, so members can't remove their last [passkey](/docs/dev/passkeys) unless they have another passkey or a linked SSO provider.

<Callout type="warn">
  The AdminCP sign-in at `/admin` keeps its email + password form, so switching member passwords off never locks your staff out. With passkeys enabled, staff can also use [AdminCP passkey sign-in](/docs/dev/passkeys/admincp). Signing out works exactly as before.
</Callout>

Password hashes already in the database are left alone, so switching `enabled` back to `true` restores password sign-in for everyone who had one.

## Learn More [#learn-more]

# Queue Tasks (/docs/dev/advanced/queue)

Queue tasks handle asynchronous, one-off background work (e.g. sending bulk emails, processing media, or scheduling posts). Tasks are persisted in the `core_queue` table and drained periodically by VitNode's background worker.

## Quick start [#quick-start]

### 1. Define a Queue Task [#1-define-a-queue-task]

```ts title="plugins/blog/src/api/tasks/send-newsletter.task.ts"
import { buildQueueTask } from "@vitnode/core/api/lib/queue"

export interface NewsletterPayload {
  postId: number
}

export const sendNewsletterTask = buildQueueTask<NewsletterPayload>({
  name: "send-newsletter",
  handler: async (c, payload) => {
    await c.get("log").info(`Processing newsletter for post #${payload.postId}`)
  },
})
```

---

### 2. Register in an API Module [#2-register-in-an-api-module]

Attach the task to your module's `queueTasks` list:

```ts title="plugins/blog/src/api/modules/posts/posts.module.ts"
import { buildModule } from "@vitnode/core/api/lib/module"
import { sendNewsletterTask } from "../../tasks/send-newsletter.task"

export const postsModule = buildModule({
  name: "posts",
  routes: [createPostRoute],
  queueTasks: [sendNewsletterTask], // [!code ++]
})
```

---

### 3. Dispatch Tasks [#3-dispatch-tasks]

Dispatch jobs from any Hono route or service:

```ts
// Dispatch immediately
await c.get("queue").dispatch({
  name: "send-newsletter",
  payload: { postId: 42 },
})

// Or schedule for future execution
await c.get("queue").dispatch({
  name: "send-newsletter",
  payload: { postId: 42 },
  executeAt: new Date(Date.now() + 60 * 60 * 1000), // 1 hour from now
  priority: 10, // Higher numbers run first
})
```

`dispatch` returns `{ id }` as soon as the task row is written to PostgreSQL.

---

## Retries and Error Handling [#retries-and-error-handling]

VitNode tasks automatically retry on failure using exponential backoff:

```ts
export const riskyTask = buildQueueTask({
  name: "sync-external-api",
  maxAttempts: 5, // Default is 3
  handler: async (c, payload) => {
    // If an error is thrown, the task retries automatically
  },
})
```

### Stale Tasks Are Reclaimed [#stale-tasks-are-reclaimed]

A task still `processing` after 15 minutes (`QUEUE_STALE_PROCESSING_MINUTES`) belonged to a worker that died mid-run. The queue worker puts it back to `pending`, or marks it `failed` if it has used every attempt, so a crash never strands a task forever.

<Callout type="warn" title="Keep handlers well under 15 minutes">
  A handler that runs longer would be reclaimed and run again while it is still going. Long work should save its progress and dispatch a follow-up task instead - the way [notification fan-out](/docs/dev/notifications/queue-and-scale) does.
</Callout>

---

## AdminCP Queue Monitor [#admincp-queue-monitor]

{/* Image prompt: VitNode AdminCP Queue Management screen at /admin/core/advanced/queue. Table displaying queued jobs with status badges (pending, processing, completed, failed), attempts count, payload JSON preview, and a retry action button. Dark theme, 1440x900. */}

Inspect and debug tasks at **Core → Advanced → Queue** (`/admin/core/advanced/queue`):
- Monitor pending, active, and failed jobs in real time.
- View failure error traces and retry failed tasks with one click.

---

## `buildQueueTask` Options [#buildqueuetask-options]

<TypeTable
  type={{
    name: {
      description: "Unique task name within the plugin.",
      required: true,
      type: "string",
    },
    handler: {
      description: "Async function executed when the task is processed.",
      required: true,
      type: "(c: Context, payload: T) => Promise<void>",
    },
    maxAttempts: {
      default: "3",
      description: "Maximum retry attempts before permanently failing.",
      type: "number",
    },
  }}
/>

## Learn More [#learn-more]

# Rate Limiter (/docs/dev/advanced/rate-limiter)

VitNode includes automated IP-based rate limiting middleware. Exceeding the request budget immediately returns `429 Too Many Requests` with a `Retry-After` header, protecting authentication and public endpoints from brute-force attacks.

## Quick start [#quick-start]

Customize the rate limiter budget in `apps/api/src/vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:4]
  rateLimiter: {
    points: 60, // Max requests allowed
    duration: 60, // Window in seconds
  },
})
```

The default configuration allows **80 requests per 60 seconds** per IP address.

IPv6 visitors are counted per `/64` network, not per address - an ISP usually hands one person a whole `/64`, and we'd rather not give them 18 quintillion fresh budgets.

## Stricter budget for sign-in [#stricter-budget-for-sign-in]

Routes that check a password or send an email to whoever is named in the request get a second, much smaller budget on top of the global one: **10 requests per 60 seconds** per IP address. That covers:

- `POST /users/sign_in` and `POST /users/sign_up`
- `POST /users/reset-password` and `POST /users/change-password`
- `POST /users/verify-email` and `POST /users/verify-email/resend`
- `POST /users/passkeys/sign-in` and `POST /users/passkeys/admin-sign-in`

Tune it with `rateLimiter.auth`:

```ts title="apps/api/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  rateLimiter: {
    // [!code ++:4]
    auth: {
      points: 5,
      duration: 60,
    },
  },
})
```

## Budget for public content writes [#budget-for-public-content-writes]

Public [Content Engine writes](/docs/content-engine/public-write) - `POST` and `PATCH` requests under a plugin's `/content/` routes, outside `/admin/` - get their own budget on top of the global one: **20 requests per 60 seconds** per IP address. It keeps one member from flooding a forum with new discussions.

Tune it with `rateLimiter.contentWrite`:

```ts title="apps/api/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  rateLimiter: {
    // [!code ++:4]
    contentWrite: {
      points: 10,
      duration: 60,
    },
  },
})
```

<Callout type="info" title="Disabled in development">
  Rate limiting is automatically bypassed when `NODE_ENV=development` to prevent interruptions during local coding.
</Callout>

---

## 429 Error Response Format [#429-error-response-format]

When a client exhausts their request allowance, the API returns a structured JSON error:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 24
Content-Type: application/json

{
  "error": "Too Many Requests",
  "retryAfter": 24
}
```

---

## Distributed Rate Limiting (Redis) [#distributed-rate-limiting-redis]

- **Without Redis**: Counters are tracked in local memory per server instance.
- **With Redis**: Counters are synchronized across all API containers using a distributed sliding window.

Configure Redis in `vitnode.api.config.ts`:

```ts
export const vitNodeApiConfig = buildApiConfig({
  redis: process.env.REDIS_URL
    ? { url: process.env.REDIS_URL, password: process.env.REDIS_PASSWORD }
    : undefined,
})
```

---

## Real visitor IPs for server-rendered pages [#real-visitor-ips-for-server-rendered-pages]

When your web app renders a page on the server, it calls the API itself - so the API sees the **web server's** address, not your visitor's. Every server-rendered request then lands in the same bucket, and 80 requests a minute disappears fast on a busy site.

The API never believes a plain `X-Forwarded-For` header (anyone can type one). Instead, the web server works out the visitor's address, signs it with a key derived from your `CRON_SECRET` - the secret the web app and the API already share - and the API checks that signature before trusting it.

- Set the same `CRON_SECRET` in both apps (you need it there anyway).
- Tell each app how many proxies sit in front of it with `VITNODE_TRUSTED_PROXY_HOPS`. It skips exactly that many hops from the right of `X-Forwarded-For` and ignores everything further left, because a visitor can write whatever they like there. The API reads it too, for browser calls that reach it through your proxy - in a split deployment, set it to the proxies in front of the **API**, and leave it at `0` if the API is only reachable from the web server.
- The API trusts the forwarded address only when the signature matches and is less than 5 minutes old.
- While `CRON_SECRET` is unset or still a published placeholder, nothing is trusted: the API keys every request on the connection address.

| Setup                                                     | `VITNODE_TRUSTED_PROXY_HOPS` |
| --------------------------------------------------------- | ---------------------------- |
| Web app exposed directly, no proxy (default)              | `0`                          |
| One reverse proxy (Nginx, Caddy, a load balancer, Vercel) | `1`                          |
| A CDN in front of your reverse proxy                      | `2`                          |

<Callout type="warn" title="Count your proxies, not your hopes">
  A number higher than the proxies you actually run lets visitors choose their own address again. With the default `0`, every server-rendered request behind a proxy shares the proxy's bucket, so the limit is safe but tight.
</Callout>

<Callout type="warn" title="One secret, two jobs">
  Anyone holding `CRON_SECRET` can trigger cron jobs and pick any IP address the rate limiter will believe. Use a long random value and rotate it in both apps together.
</Callout>

---

## `rateLimiter` Options [#ratelimiter-options]

## Learn More [#learn-more]

# Redis (/docs/dev/advanced/redis)

[Redis](https://redis.io) serves as VitNode's shared cache and pub/sub broker across horizontally scaled instances. Redis is optional: without it, VitNode degrades gracefully to in-memory counters and local delivery.

## Quick start [#quick-start]

### 1. Configure Environment Variables [#1-configure-environment-variables]

```bash title=".env"
REDIS_URL=redis://localhost:6379 // [!code ++]
REDIS_PASSWORD=root // [!code ++]
```

### 2. Connect in API Configuration [#2-connect-in-api-configuration]

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:5]
  redis: process.env.REDIS_URL
    ? { url: process.env.REDIS_URL, password: process.env.REDIS_PASSWORD }
    : undefined,
})
```

---

## What Redis Powers [#what-redis-powers]

---

## Local Development (Docker) [#local-development-docker]

Start a Redis container with Docker Compose:

```yaml title="docker-compose.yml"
services:
  redis:
    image: redis:7-alpine
    restart: always
    ports:
      - "6379:6379"
    command: redis-server --requirepass root
```

---

## Using the Cache in API Routes [#using-the-cache-in-api-routes]

Use `remember` with a key, a TTL in seconds, and a loader to cache expensive database lookups:

```ts
const posts = await c.get("cache").remember(
  "featured_posts",
  60,
  async () => await fetchFeaturedPostsFromDB(),
)
```

See [Cache API data](/docs/dev/cache/api) for invalidation and the full method list.

---

## Verifying Redis in AdminCP [#verifying-redis-in-admincp]

{/* Image prompt: VitNode AdminCP System -> Diagnostics screen at /admin/core/advanced/debug. System health card shows Redis status "Connected" with latency graph, memory usage, and ping metrics. Dark theme, 1440x900. */}

Check Redis connection health anytime under **Core → Advanced → Debug** (`/admin/core/advanced/debug`).

## Learn More [#learn-more]

# AI Actions (/docs/dev/ai/actions)

An **AI action** is one AI feature a plugin offers, such as "write an excerpt", "translate a field" or "suggest tags". The plugin describes the prompt and the input and output shapes. VitNode Core runs it: it picks the model, checks permissions, enforces limits, holds budget, calls the provider, validates the answer and records what it cost.

```ts
const { output } = await c.get('ai').run({
  action: EXCERPT_AI_ACTION,
  input: { title, content, locale },
})
```

## Why actions exist [#why-actions-exist]

Calling `generateText` with `c.get("ai").model()` works, but every plugin would then need its own answers to the same questions: who may use this, how much can they spend, what happens when the provider times out, and where did the money go?

Actions answer those once, in Core:

- **One place for models.** Admins choose the model, fallback and limits per action in the AdminCP. Plugins never hard-code a model.
- **One place for limits.** Permissions, daily limits, rate limits and concurrency apply to every action the same way.
- **One place for accounting.** Every run and every provider call is recorded with tokens and cost, and charged to the right [budget](/docs/dev/ai/costs-and-limits).

<Callout type="info" title="Use actions for anything users can trigger">
  Direct SDK calls with `c.get("ai").model()` bypass budgets, limits and
  history. Keep them for internal tooling you fully control.
</Callout>

## Create an action [#create-an-action]

This example adds a "summarize topic" button to a forum plugin's AdminCP.

<Steps>

<Step>

### Define the action [#define-the-action]

```ts title="plugins/forum/src/api/ai/actions.ts"
import { defineAiAction } from '@vitnode/core/api/lib/ai/action'
import { aiActionRef } from '@vitnode/core/api/lib/ai/registry'
import { checkStaffPermission } from '@vitnode/core/api/lib/check-staff-permission'
import { z } from 'zod'

import { CONFIG_PLUGIN } from '@/const'

export const zodSummarizeTopicSchema = z.object({
  title: z.string().trim().min(1).max(255),
  content: z.string().trim().min(1).max(50_000),
})

export const summarizeTopicAiAction = defineAiAction({
  id: 'topic.summarize',
  title: 'ai_actions.@vitnode/forum.topic_summarize.title',
  description: 'ai_actions.@vitnode/forum.topic_summarize.description',
  icon: 'text-quote',
  promptVersion: 1,
  permission: { key: 'summarize', defaultGranted: true },
  requiredCapabilities: ['text'],
  defaults: {
    maxInputCharacters: 50_000,
    maxOutputTokens: 300,
    timeoutMs: 30_000,
  },
  inputSchema: zodSummarizeTopicSchema,
  output: 'text',
  outputSchema: z.string().min(1).max(600),
  parseText: (text) => text.trim(),
  buildPrompt: (input, { instructions }) => ({
    system: ['Summarize the forum topic in two plain sentences.', instructions]
      .filter(Boolean)
      .join('\n'),
    prompt: `${input.title}\n\n${input.content}`,
  }),
  // The AI permission never replaces access to the content itself.
  authorize: async ({ c }) =>
    await checkStaffPermission(c, {
      type: 'admin',
      plugin: CONFIG_PLUGIN.pluginId,
      module: 'topics',
      permission: 'can_view',
    }),
})

export const forumAiActions = [summarizeTopicAiAction]

export const SUMMARIZE_TOPIC_AI_ACTION = aiActionRef(
  CONFIG_PLUGIN.pluginId,
  summarizeTopicAiAction,
)
```

`title` and `description` are message keys. Add their text to the plugin's
messages in the next step.

`defineAiAction()` validates the definition when the module loads. A bad id, a missing `authorize()` or an out-of-range limit throws an `AiActionDefinitionError` at boot, not in production traffic.

</Step>

<Step>

### Add the title and description [#add-the-title-and-description]

Add the text to the plugin's messages, under the shared `ai_actions` key and
your plugin id. Every AI page loads `ai_actions` as one namespace, so all
plugins' action names arrive together.

```json title="plugins/forum/src/locales/en.json"
{
  "ai_actions": {
    "@vitnode/forum": {
      "topic_summarize": {
        "title": "Summarize topic",
        "description": "Writes a two-sentence summary of a forum topic."
      }
    }
  }
}
```

</Step>

<Step>

### Register it in the plugin [#register-it-in-the-plugin]

```ts title="plugins/forum/src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { forumAiActions } from '@/api/ai/actions'
import { adminModule } from '@/api/modules/admin/admin.module'
import { CONFIG_PLUGIN } from '@/const'

export const forumApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    aiActions: forumAiActions, // [!code ++]
    modules: [adminModule],
  })
```

</Step>

<Step>

### Run it from a route [#run-it-from-a-route]

```ts title="plugins/forum/src/api/modules/admin/ai/routes/summarize.route.ts"
import { buildRoute } from '@vitnode/core/api/lib/route'
import { z } from 'zod'

import {
  SUMMARIZE_TOPIC_AI_ACTION,
  zodSummarizeTopicSchema,
} from '@/api/ai/actions'
import { CONFIG_PLUGIN } from '@/const'

export const summarizeTopicRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  adminStaffPermission: { module: 'topics', permission: 'can_view' },
  route: {
    method: 'post',
    description: 'Summarize a forum topic with the configured AI model.',
    path: '/summarize',
    request: {
      body: {
        required: true,
        content: { 'application/json': { schema: zodSummarizeTopicSchema } },
      },
    },
    responses: {
      200: {
        content: {
          'application/json': { schema: z.object({ text: z.string() }) },
        },
        description: 'The summary',
      },
      403: { description: 'No access to topics or to this AI feature' },
      429: { description: 'A personal AI limit was reached' },
      502: { description: 'The AI provider failed or answered unusably' },
      503: { description: 'AI is switched off or the site budget is used up' },
    },
  },
  handler: async (c) => {
    // [!code ++:4]
    const { output } = await c.get('ai').run({
      action: SUMMARIZE_TOPIC_AI_ACTION,
      input: c.req.valid('json'),
    })

return c.json({ text: output }, 200)
  },
})
```

TypeScript infers `output` as `string` from the action's `outputSchema`. When the run fails, `run()` throws an `AiError` and the route answers with its [error code](#error-codes).

</Step>

</Steps>

For a complete, real example, read the `@vitnode/blog` plugin: `plugins/blog/src/api/ai/actions.ts` and its `admin/ai` routes.

## Action ids [#action-ids]

An action has a **local id**, unique inside its plugin: lowercase, dot-separated words such as `topic.summarize`.

Core stores it under a **canonical key**, `<pluginId>:<localId>`:

```text
@acme/forum:topic.summarize
@vitnode/blog:excerpt.generate
```

Two plugins may both have an `excerpt.generate`; their canonical keys differ. The same canonical key twice throws at boot. Settings, history and limits all use the canonical key.

`aiActionRef(pluginId, action)` builds the canonical key **and** remembers the action's input and output types. Pass it to `run()` and TypeScript checks `input` and infers `output`. A plain string key also works, but its output is `unknown`.

## Title, description and icon [#title-description-and-icon]

Every action appears as a row on **Artificial Intelligence (AI) → Actions**, as a feature on the role form's **Artificial intelligence (AI)** tab and in a member's AI usage. Each of those needs a human name in every language:

- **`title`** (required): the message key of a short name, e.g. `ai_actions.@vitnode/forum.topic_summarize.title` for "Summarize topic".
- **`description`** (required): the message key of one sentence on what it does.
- **`icon`** (optional): a [Lucide](https://lucide.dev/icons) icon name in kebab case, e.g. `languages` or `wand-sparkles`. Without one, the row shows a sparkles icon.

The API returns both keys untranslated. The AdminCP and the member's settings translate them into the page's language. A language without the key falls back to the default language's text. Keep the keys in your plugin's `src/locales/en.json` under `ai_actions` → your plugin id, and translate them like any other [plugin message](/docs/dev/i18n/messages).

<Callout type="info" title="Plain text still works">
  A `title` or `description` that is not a message key is shown as written. That
  is handy while prototyping, but it never gets translated.
</Callout>

A blank title or description, or an icon that isn't a kebab-case name, throws at boot.

## Prompt versions and instructions [#prompt-versions-and-instructions]

`promptVersion` is stored with every run. Bump it whenever the prompt changes meaningfully, so the history shows which prompt produced which result.

`buildPrompt(input, { instructions })` returns either `{ prompt, system? }` or `{ messages, system? }`. `instructions` is optional extra guidance an admin set for this action in the AdminCP, or `null`. Append it to the system prompt.

## Input and output [#input-and-output]

- **`inputSchema`** (Zod) validates the input before anything else happens. Invalid input fails with `AI_INVALID_INPUT`.
- **`measureInput(input)`** returns the number of characters counted against `maxInputCharacters`. By default every string in the input counts. Override it when only part of the input reaches the prompt. The blog excerpt, for example, counts only the text it extracts from the HTML.
- **`output: "text"`** makes the model return text. `parseText(text, input)` turns it into your output, then `outputSchema` checks it. Throw from `parseText()` to reject an answer.
- **`output: "object"`** makes the model return structured JSON, which `outputSchema` validates. The action must require the `structured-output` capability, and it cannot be streamed.

An empty answer, a `parseText()` that throws or a schema mismatch fails with `AI_INVALID_OUTPUT`. The user is not charged for it.

```ts title="An object action"
export const suggestTagsAiAction = defineAiAction({
  id: 'topic.tags',
  title: 'ai_actions.@vitnode/forum.topic_tags.title',
  description: 'ai_actions.@vitnode/forum.topic_tags.description',
  promptVersion: 1,
  permission: 'tags',
  actors: ['system'],
  requiredCapabilities: ['text', 'structured-output'],
  defaults: {
    maxInputCharacters: 20_000,
    maxOutputTokens: 200,
    timeoutMs: 30_000,
    maxRetries: 1,
  },
  inputSchema: z.object({ content: z.string().min(1) }),
  output: 'object',
  outputSchema: z.object({ tags: z.array(z.string().max(32)).max(5) }),
  buildPrompt: (input) => ({
    system: 'Suggest up to five short, lowercase tags for this forum topic.',
    prompt: input.content,
  }),
})

export const TOPIC_TAGS_AI_ACTION = aiActionRef(
  CONFIG_PLUGIN.pluginId,
  suggestTagsAiAction,
)
```

`actors: ["system"]` makes this a background-only action, so it needs no `authorize()`. See [Actors](#actors-users-and-the-system).

### Images [#images]

For a vision action, require `image-input` and pass the image **bytes** as a `file` part. Read them server-side, for example with `c.get("storage").readBytes(key, maxBytes)`, so no private file ever has to be made public for the provider:

```ts
buildPrompt: (input) => ({
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Describe this image in one sentence.' },
        { type: 'file', data: input.image, mediaType: input.mediaType },
      ],
    },
  ],
}),
```

`maxImages` defaults to `1` for these actions and bounds how many images one run may send. Only models that declare `image-input` are used. See [Model capabilities](/docs/dev/ai#model-capabilities).

## Permissions and authorize() [#permissions-and-authorize]

Every action names a **permission**. Admins grant it per role on the **Artificial intelligence (AI)** tab of the role form. Several actions may share one key. They then share one switch and one daily counter.

```ts
permission: 'summarize' // same as { key: 'summarize', defaultGranted: false }
permission: { key: 'summarize', defaultGranted: true }
```

`defaultGranted` applies while no role has a setting for the key. The canonical permission is `<pluginId>:<key>`. Two actions sharing a key must agree on `defaultGranted`, or boot fails.

`authorize()` is **required** for actions users can run. The AI permission says "this role may use AI summaries". `authorize()` says "this user may read _this_ topic". Both must pass:

```ts
// canReadTopic() is the forum plugin's own access check
authorize: async ({ c, input, userId }) =>
  await canReadTopic(c, { topicId: input.topicId, userId }),
```

`resource` is the optional `{ type, id }` the caller passed to `run()`. It is also stored with the run, so history can link back to the content.

## Actors: users and the system [#actors-users-and-the-system]

`actors` decides who may run an action. The server sets the actor; the request never does.

The default is `["user"]`. `run()` uses the signed-in AdminCP user first, then the site user. Without one, it fails with `AI_UNAUTHORIZED`.

Use `runAsSystem()` only from trusted server code: cron jobs, queue tasks, event listeners. No route should pass a client's request into it.

```ts title="plugins/forum/src/api/cron/tag-topics.cron.ts"
import { isAiError } from '@vitnode/core/api/lib/ai/errors'
import { buildCron } from '@vitnode/core/api/lib/cron'

import { TOPIC_TAGS_AI_ACTION } from '@/api/ai/actions'

export const tagTopicsCron = buildCron({
  name: 'tag-new-topics',
  description: 'Suggest tags for new forum topics',
  schedule: '*/15 * * * *',
  handler: async (c) => {
    for (const topic of await loadUntaggedTopics(c)) {
      try {
        const { output } = await c.get('ai').runAsSystem({
          action: TOPIC_TAGS_AI_ACTION,
          input: { content: topic.content },
          resource: { type: 'forum_topic', id: topic.id },
        })
        await saveTopicTags(c, topic.id, output.tags)
      } catch (error) {
        // Out of budget: stop now and try again on the next tick.
        if (isAiError(error) && error.code === 'AI_BUDGET_EXHAUSTED') return
        throw error
      }
    }
  },
})
```

## Defaults and limits [#defaults-and-limits]

`defaults` sets an action's limits. Admins can override most of them per action in the AdminCP. Values outside the allowed range throw at boot.

| Field                | Required | Default                          | Range           |
| :------------------- | :------- | :------------------------------- | :-------------- |
| `maxInputCharacters` | Yes      | -                                | 1 – 1,000,000   |
| `maxOutputTokens`    | Yes      | -                                | 1 – 200,000     |
| `timeoutMs`          | Yes      | -                                | 1,000 – 600,000 |
| `maxRetries`         | No       | `0`                              | 0 – 3           |
| `maxSteps`           | No       | `1`                              | 1 – 10          |
| `maxImages`          | No       | `1` with `image-input`, else `0` | 0 – 10          |
| `dailyLimit`         | No       | `null` (no limit)                | 0 – 100,000     |

- `timeoutMs` applies to each attempt.
- `maxRetries` is extra attempts on the same model after a failed provider call.
- `maxSteps` is model round trips inside one attempt (tool loops). Each step is billed as its own call.
- `dailyLimit` counts runs per user per day for the action's permission key. A role's daily limit takes precedence over the admin's action setting, which takes precedence over this default.
- Admins cannot change `maxImages`, because it bounds the budget reserved for images.

Admins can also, per action: switch it off, assign a model, assign a fallback model, and add `instructions`.

## Run options [#run-options]

`run()` and `runAsSystem()` resolve to:

```ts
{
  output: Output,      // validated by outputSchema
  runId: number,
  usage: {
    chargedPoints: string, // points charged to the user, full precision; "0" for system runs
    costKnown: boolean,
    modelId: string,       // the configured model that answered
  },
}
```

You can safely return `usage` to the browser: it never contains prices or provider details.

## What happens during a run [#what-happens-during-a-run]

1. Find the action, check the actor, validate `input`.
2. Check the global AI switch and the action's switch.
3. For users: check the role permission, then `authorize()`.
4. Measure the input and the number of images.
5. Pick the model: the admin's choice, or the first configured model with every required capability. Resolve the optional fallback, skipping an incompatible one.
6. **Reserve** budget for the worst case and check rate and concurrency limits, in one short database transaction.
7. Call the provider outside any transaction. Retry up to `maxRetries` times, then try the fallback model once.
8. Validate the output.
9. **Settle**: charge the real cost and release the rest of the reservation.
10. Emit `ai.run.completed` or `ai.run.failed`.

A canceled run stops immediately. An invalid answer is not retried on the same model, but the fallback model still gets one try. Everything before step 6 costs nothing. [Costs, Points & Budgets](/docs/dev/ai/costs-and-limits) explains steps 6 and 9.

## Stream a text action [#stream-a-text-action]

`c.get("ai").stream()` streams a `text` action for the signed-in user. Object actions cannot be streamed.

```ts
handler: async (c) => {
  const { textStream } = await c.get('ai').stream({
    action: SUMMARIZE_TOPIC_AI_ACTION,
    input: c.req.valid('json'),
    signal: c.req.raw.signal, // stop paying when the reader leaves
  })

return new Response(textStream.pipeThrough(new TextEncoderStream()), {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  })
}
```

The stream also returns `result`, a promise that resolves to the validated output once the stream ends, and rejects with an `AiError` if the full text is invalid. A stream makes one attempt on the primary model, with no retries and no fallback. If the reader cancels, the run settles as `canceled` and the user is not charged.

## Error codes [#error-codes]

Every refusal and failure is an `AiError` with a stable `code`. Routes answer with this JSON body. Key the browser's messages on `code`, never on the English `message`:

```json
{
  "code": "AI_USER_LIMIT_REACHED",
  "message": "You used all your AI points for this period.",
  "resetsAt": "2026-11-01T00:00:00.000Z",
  "runId": 42
}
```

`resetsAt` is set for limit and budget errors. `runId` is set when a run was recorded.

Import the helpers from `@vitnode/core/api/lib/ai/errors`: `AiError`, `isAiError()`, `AI_ERROR_CODES` and `AI_ERROR_STATUS`.

## Events [#events]

Each run that got past the reservation emits one event after it settles:

`userId` is `null` for system runs. Refusals before the reservation, such as a missing permission or a reached limit, emit nothing. A listener that throws never breaks the run.

```ts title="plugins/forum/src/api/lib/ai-events.ts"
import { buildEventListener } from '@vitnode/core/api/lib/events'

export const aiFailureListener = buildEventListener({
  event: 'ai.run.failed',
  name: 'log-ai-failures',
  handler: async (c, payload) => {
    if (!payload.actionKey.startsWith('@acme/forum:')) return
    await c
      .get('log')
      .warn(`AI run ${payload.runId} failed: ${payload.errorCode}`)
  },
})
```

See [Events](/docs/dev/events) for registering listeners.

## Learn more [#learn-more]

# AdminCP & Account Usage (/docs/dev/ai/admin)

The AdminCP **Artificial Intelligence (AI)** section (`/admin/core/ai`) is where admins decide how much the site may spend on AI, which models run which features, and who may use them. Members see their own allowance at **Settings → AI usage** (`/settings/ai`).

| Page                                     | URL                            | What it is for                                               |
| :--------------------------------------- | :----------------------------- | :----------------------------------------------------------- |
| Overview                                 | `/admin/core/ai`               | Spend against the budget, a forecast, trends and breakdowns. |
| Settings sheet                           | `/admin/core/ai?settings=open` | Global switch, budgets, rate limits, retention, ALT text.    |
| Actions                                  | `/admin/core/ai/actions`       | Every registered AI feature: switch, model, limits.          |
| History                                  | `/admin/core/ai/history`       | Every run: who, which model, tokens and cost.                |
| Roles → Artificial intelligence (AI) tab | `/admin/core/users/roles`      | A role's AI permissions, monthly points and daily limits.    |
| User → AI card                           | `/admin/core/users/{id}`       | One member's exception: blocked, unlimited or own points.    |
| AI usage                                 | `/settings/ai` (member)        | A member's own points and what each AI feature cost them.    |

Models and their prices are not edited in the AdminCP. They live in `vitnode.api.config.ts`, next to the provider keys they need. See [Model pricing](/docs/dev/ai/costs-and-limits#model-pricing).

## First-time setup [#first-time-setup]

[AI Setup](/docs/dev/ai) covers the models and prices you set in code. Everything after that happens in the AdminCP.

<Steps>

<Step>

### Set a monthly site budget [#set-a-monthly-site-budget]

Open **Artificial Intelligence (AI) → Overview**, click **Settings** and, under **Budget**, set **Monthly site budget** in USD. Without it, nothing caps what the whole site spends. Automatic ALT text refuses to turn on until a budget exists.

</Step>

<Step>

### Give every model a price [#give-every-model-a-price]

Add `pricing` to each model in `vitnode.api.config.ts`. A model without a price makes every run's cost unknown, and under a budget cap it is refused with `AI_PRICING_MISSING`.

</Step>

<Step>

### Grant roles access and points [#grant-roles-access-and-points]

Open **Users → Roles**, edit a role and switch to the **Artificial intelligence (AI)** tab. Give the role a monthly allowance (or **Unlimited points**) and allow the features it should use. The default monthly points are `0`, so only root roles can run priced features until you do this.

</Step>

<Step>

### Optionally turn on automatic ALT text [#optionally-turn-on-automatic-alt-text]

In the same **Settings** sheet, under **ALT text**, switch on **Write ALT text automatically**. You need a vision model (`image-input`) with pricing and a running cron. See [Automatic Image ALT Text](/docs/dev/ai/automatic-alt).

</Step>

</Steps>

## Staff permissions [#staff-permissions]

The AI screens use two staff permissions in the `ai` module of `@vitnode/core`. Grant them in **Staff → Administrators** like any other [staff permission](/docs/dev/working-with-users/staff-permissions).

| Permission      | Allows                                                                                                                                  |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
| `ai:can_view`   | Open every AI page, read overview, actions, history and settings, and see a member's AI exception.                                      |
| `ai:can_manage` | Change settings and action settings, the **Artificial intelligence (AI)** tab on roles and a member's exception. Depends on `can_view`. |

Without `can_manage`, the pages are read-only: forms are disabled, write buttons are hidden and the role form has no **Artificial intelligence (AI)** tab.

<Callout type="info" title="Staff permissions are not AI permissions">
  `ai:can_manage` lets an admin _configure_ AI. Whether that admin may _use_ a
  feature, such as an excerpt button or Quick Ask, depends on the **Artificial
  intelligence (AI)** tab of their roles, the same as for everyone else.
</Callout>

## Settings [#settings]

The **Settings** button on **Artificial Intelligence (AI) → Overview** opens a sheet with the rules every run follows. Changes apply from the next run, after you press **Save settings**. The sheet has its own link, `/admin/core/ai?settings=open`, so you can send it to another admin.

Switch **AI features** off and the rest of the sheet hides, because none of it applies while AI is off.

Budgets and allowances are calendar months in the **site's time zone** (the default language's). The settings sheet shows which one.

Budgets are in **USD**, because that is what providers bill. Members are charged in **AI points**. [Costs, Points & Budgets](/docs/dev/ai/costs-and-limits) explains the conversion and what happens on failure.

## Actions [#actions]

**Artificial Intelligence (AI) → Actions** lists every [AI action](/docs/dev/ai/actions) installed plugins register, grouped by the plugin it comes from. Each row shows the action's icon, title and description in your language. Badges appear only when something differs from the default: a chosen model, a daily limit, or a warning that no configured model can run the action. Search by title, description or key, or filter by plugin.

The switch on each row turns the action on or off straight away. A disabled action refuses to run for anyone, and its row fades.

The **Configure** button (the gear) opens a sheet with the rest:

- **Enabled**: the same switch as on the row.
- **Model** and **Fallback model**: only models with every capability the action needs are listed. **Site default** is the first compatible model.
- **Editorial instructions**: up to 2,000 characters appended to the prompt, e.g. house style.
- **Limits**: runs per member per day, max input characters, max output tokens, retries, steps and timeout. Each one can fall back to the plugin's default.

Press **Save action** to apply the changes from the next run. An action marked _No compatible model, so it can't run_ needs a model with the right capabilities in `vitnode.api.config.ts` first.

## AI access [#ai-access]

A member's run must pass four separate controls. They answer different questions, so check the right one when somebody is refused:

The permission does not replace content access. An excerpt action still checks that the admin may edit the article.

### Roles [#roles]

Creating or editing a role in **Users → Roles** shows an **Artificial intelligence (AI)** tab to admins with `ai:can_manage`. It sets:

- **Allowance**: monthly points, **Unlimited points**, or the site default.
- **Features**: one row per AI permission, showing the icon, title and description of every action that uses it. Pick _Default_, _Allow_ or _Deny_; _Allow_ opens an optional daily limit in the same row. Icons turn grey when the role can't use the feature.

The AI access is saved together with the role, right after it.

A member with several roles gets the **largest** allowance (never the sum), the broadest permissions and the largest daily limit. Root roles always have access and no point cap, but the site budget still applies to them.

### User exceptions [#user-exceptions]

The **AI access** card on a member's AdminCP page (**Users → a member**) gives them their own rule, ahead of their roles: **Block AI features**, **Unlimited points**, or a personal monthly allowance. It replaces what their roles give until you remove it.

## History [#history]

**Artificial Intelligence (AI) → History** lists every run with its action, status, origin (Members or Background jobs), model, cost and points. Filter by status, origin, action or model. **Details** shows:

- tokens in and out, cost, cost source and what was charged or reserved;
- every provider call, with retries and fallbacks listed as separate calls;
- cost corrections made by reconciliation;
- whether an editor accepted the suggestion (tracking only, never billing).

<Callout type="info" title="Prompts and outputs are never stored">
  History records what a run took and what it cost. It never keeps the prompt,
  the input text or the generated text. The same is true on the member's page.
</Callout>

Run statuses: `reserved`, `running`, `succeeded`, `failed`, `canceled` and `uncertain` (the process died mid-call; the maintenance cron settles it). The `ai-maintenance` cron prunes history older than **Keep history for**.

## Overview [#overview]

**Artificial Intelligence (AI) → Overview** answers two questions: _will we stay inside the budget?_ and _where does the money go?_

- **Date range** (top right): This month (the default), Last month, the last 7, 30 or 90 days, or any range picked on the calendar. Every number below follows it, and each is compared with the range before it: this month so far with the same days of last month, a whole month with the month before, anything else with the same number of days just before it.
- **Budget**: what the month has charged to the budget and the share of the limit used, with a mark where an even pace would be today. The bar turns amber at 80% of the limit (or when the forecast goes over it) and red at 90%. The arrows next to the month's name step through earlier months.
  - For this month you get a forecast: what is already charged, plus the selected range's daily average for every day left. Pick **Last 7 days** to forecast from recent days, or **Last 90 days** for a steadier average. Going over turns the note amber.
  - For an earlier month you get how it closed, and what a month would cost at the selected range's pace.
- **Six numbers**: spend, cost per run, runs, failure rate, tokens and the share of runs with a known cost, each with its change. Click one to chart it.
- **Chart**: for spend, the month's running total against the budget line, with last month dashed and the forecast to the month's end. For the other numbers, a running total (or a running average for rates) across the range, against the range before it.
- **Where it goes**: the picked number by action or by model, ranked, with a mark for the range before. A run whose model has no price shows **Unknown**, never `$0`, and the page tells you how many runs that is.

The range and the budget month live in the URL (`?range=7d`, `?from=2026-09-12&to=2026-09-25`, `?month=2026-09`), so a view can be shared with another admin. Days follow the site's time zone, shown in the **Settings** sheet.

## Member page: /settings/ai [#member-page-settingsai]

Members who can use at least one AI feature get **Settings → AI usage**. Members without any feature, or on a site with AI switched off, don't see it in the settings menu, and opening the URL shows a not-found page. The page reads only the member's own data:

- **Monthly points**: points left, the share used and the renewal date. The bar turns amber at 80% used and red at 90%. Unused points do not roll over.
- **Your AI features**: one row per feature they may use, with today's runs against its daily limit and the points it cost this month. Opening a row loads that feature's latest runs with their status and points. Prompts and generated text are never stored.

The same points bar sits in its own **AI points** group at the bottom of **Settings → Overview**, with a link to the full page.

A notice under the points bar explains why AI may not be working, checked in this order:

## API routes [#api-routes]

Every screen is backed by an API route under `@vitnode/core`. Use them with [`fetcher`](/docs/dev/fetcher), e.g. `fetcher({ plugin: '@vitnode/core', method: 'get', module: 'admin/ai', path: '/overview' })`.

| Route                                         | Staff permission | Purpose                                             |
| :-------------------------------------------- | :--------------- | :-------------------------------------------------- |
| `GET /admin/ai/overview`                      | `ai:can_view`    | Overview for `range` or `from`/`to`, budget `month` |
| `GET /admin/ai/settings`, `PUT …/settings`    | view / manage    | Site-wide settings                                  |
| `GET /admin/ai/models`                        | `ai:can_view`    | Configured models (read only)                       |
| `GET /admin/ai/actions`, `PUT …/actions`      | view / manage    | Action list and per-action settings                 |
| `GET /admin/ai/access/roles?roleId=`          | `ai:can_view`    | AI permissions and one role's access                |
| `PUT /admin/ai/access/roles`                  | `ai:can_manage`  | A role's allowance and permissions                  |
| `GET /admin/ai/access/users/{userId}`         | `ai:can_view`    | One member's exception                              |
| `PUT`, `DELETE /admin/ai/access/users`        | `ai:can_manage`  | A user exception                                    |
| `GET /admin/ai/history`, `GET …/history/{id}` | `ai:can_view`    | Runs and one run's details                          |
| `GET /ai/usage`                               | signed in        | The member's own allowance, notices and features    |
| `GET /ai/history?action=&limit=`              | signed in        | The member's own runs, optionally for one feature   |

## Learn more [#learn-more]

# Automatic Image ALT Text (/docs/dev/ai/automatic-alt)

Automatic ALT text describes images in Core Files with a vision model, once per image, and translates that description into each site language. It runs in the background as the **system actor**, so it never spends a member's AI points. It is **off by default**.

```tsx title="plugins/blog/src/pages/post-page.tsx"
import { resolveImageAlt } from '@vitnode/core/lib/files/resolve-alt'

;<img
  alt={
    resolveImageAlt({
      alts: item.coverImage.alts, // the file's ALT per language
      fallbackLocales: [defaultLocale],
      locale,
      occurrence: { alt: item.coverImageAlt }, // this article's own ALT
    }).alt
  }
  src={item.coverImage.url}
/>
```

## Turn it on [#turn-it-on]

<Steps>

<Step>

### Configure a vision model with pricing [#configure-a-vision-model-with-pricing]

At least one model must declare `image-input` (the description) and `text` (the translations), and both need [pricing](/docs/dev/ai#model-pricing). The feature always runs under a budget, so VitNode refuses an unpriced model with `AI_PRICING_MISSING`.

```ts title="apps/api/src/vitnode.api.config.ts"
{
  id: 'default',
  name: 'GPT-4o Mini',
  model: openai('gpt-4o-mini'),
  capabilities: ['text', 'image-input', 'structured-output', 'streaming'], // [!code highlight]
  pricing: { rates: { inputPerMillion: '0.15', outputPerMillion: '0.60' } },
}
```

</Step>

<Step>

### Set a site budget [#set-a-site-budget]

On **Artificial Intelligence (AI) → Overview**, click **Settings** and, under **Budget**, set **Monthly site budget**. Automatic ALT cannot be switched on without one: the API answers `400` and the form shows _"Set a monthly site budget before turning on automatic ALT text."_ You can also set **Background jobs budget** to cap system work separately. It counts inside the site budget.

</Step>

<Step>

### Switch it on [#switch-it-on]

In the same **Settings** sheet, under **ALT text**:

- **Write ALT text automatically.** Turns the feature on.
- **Images queued per sweep.** How many images one hourly sweep queues (default `10`, max `100`).

The job writes ALT text in every language in `core_languages`. Add a language and the next sweep fills it in.

</Step>

<Step>

### Make sure the cron runs [#make-sure-the-cron-runs]

Nothing happens until the host runs VitNode's cron. See [Running the cron](#running-the-cron).

</Step>

</Steps>

## How it works [#how-it-works]

1. **Upload.** A new JPEG, PNG, GIF or WebP in `core_files` is queued right away when the feature is on. A failure to queue never fails the upload.
2. **Sweep.** The `ai-alt-detect` cron (hourly) looks for images still missing ALT in a configured language and queues them.
3. **Work.** The `ai-queue` cron (every minute) takes up to **2** queued images and describes them.
4. **Describe once.** The image gets one base description in English, per file fingerprint.
5. **Translate.** Each missing language gets a translation of that base description. English uses it as-is.
6. **Write.** Each language goes to `core_files_alt`, but only if no person wrote it and the file is still the same version.
7. **Notify.** `files.alt.updated` is emitted with the languages that were written.

### One description per image, translations per language [#one-description-per-image-translations-per-language]

The base description is stored in `core_files_alt_analysis`, keyed by the file and its **fingerprint** (SHA-256 of the stored bytes). When you add a language later, the sweep notices the gap and only the translation runs. The image does not go back to the vision model.

When a file's bytes change, its fingerprint changes. AI texts written for the old fingerprint count as missing, so the image is described again. The file ALT API marks such texts as `stale` until then.

### People always win [#people-always-win]

The job never overwrites a row with `origin: "human"`, whether on a new run, on a retry or after the file changes. That includes an **empty** human text: an empty string means "a person decided this image needs no description", which is different from no row at all.

To let the job write a language again, delete that language's ALT row.

### Per-file policy [#per-file-policy]

Each file has an `altPolicy`:

The job checks the policy again at write time, so a policy changed mid-run still wins.

### The sweep [#the-sweep]

The sweep walks `core_files` in id order from a stored cursor, at most 200 files per run, and queues up to **Images queued per sweep** of them. When it reaches the end, it wraps to the start, so it revisits every image and finds any new language or missed upload.

Queuing is deduplicated: a file that is already pending or processing in the queue is not queued twice.

### Budget waits are not failures [#budget-waits-are-not-failures]

When the site budget, the background jobs budget or the global switch stops a run, the task is **deferred**, not failed. It goes back to `pending` without spending a retry, with the file's state set to `waiting_budget`. It wakes at the start of the next budget month or in one hour, whichever comes first. Raise the budget mid-month and work resumes within the hour.

Other failures (provider error, invalid output, timeout) use the normal queue retries: 3 attempts, then the file's state is `failed`. The next sweep wrap queues it again.

### Its own queue [#its-own-queue]

ALT tasks run on a dedicated `ai` queue. The general `process-queue` worker skips it, and `ai-queue` processes it under its own lock with a batch of 2. A slow vision model never delays e-mails or other queue work.

Each task has a 15-minute lease. A worker that dies mid-task leaves it `processing`; once the lease expires it goes back to `pending` (the attempt is spent), or to `failed` when no attempts are left. The AI run it started is settled as `uncertain` by `ai-maintenance` and charged at its reservation.

<Callout type="warn" title="No exactly-once promise">
  Results are saved as soon as they exist, and a retry reuses the stored base
  description. A second worker waits while another one is describing the same
  image version. But a crash mid-call can still repeat one provider call: the
  one that was in flight.
</Callout>

### Image bytes stay private [#image-bytes-stay-private]

The job reads the image **server-side** and sends bytes to the provider, never a URL:

- through the storage adapter's optional `read(key, { maxBytes })` method (the Local adapter has one);
- otherwise by a bounded server-side `fetch()` of the adapter's URL.

Files over 20 MB are skipped. With `sharp` installed, the copy sent to the provider is resized to at most 1024 px and re-encoded as WebP. A private file never has to be made public for the AI provider.

## Render the ALT text [#render-the-alt-text]

For images that have ALT text, Content Engine file descriptors carry it as `alts`, a map of language code to text:

```ts
{
  id: 42,
  name: 'bike.jpg',
  url: 'https://example.com/uploads/bike.jpg',
  mimeType: 'image/jpeg',
  alts: { en: 'A red bicycle leaning on a brick wall', pl: 'Czerwony rower oparty o ceglaną ścianę' },
  // ...
}
```

`resolveImageAlt()` from `@vitnode/core/lib/files/resolve-alt` picks the text for one place the image appears, in this order:

The article's own ALT text always wins over the file's default. The blog's post page (`plugins/blog/src/pages/post-page.tsx`) is a complete example.

## Running the cron [#running-the-cron]

ALT text depends on three cron jobs registered by `@vitnode/core`:

| Job              | Schedule       | Does                                                 |
| :--------------- | :------------- | :--------------------------------------------------- |
| `ai-queue`       | `* * * * *`    | Works the `ai` queue, 2 tasks per run.               |
| `ai-alt-detect`  | `0 * * * *`    | The sweep: queues images missing ALT text.           |
| `ai-maintenance` | `*/10 * * * *` | Settles dead runs, reconciles costs, prunes history. |

Registering a cron job does not run it. The host must call VitNode's cron endpoint, in one of two ways.

**In-process.** On a long-running server, register the Node CRON adapter. It calls the endpoint every minute:

```ts title="apps/api/src/vitnode.api.config.ts"
import { NodeCronAdapter } from '@vitnode/node-cron'
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  cron: NodeCronAdapter(), // [!code ++]
  // ...
})
```

**External scheduler.** On serverless hosting nothing stays alive to hold a timer, so an external scheduler must call the endpoint, ideally once a minute:

```bash
curl -X POST https://example.com/api/@vitnode/core/cron \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CRON_SECRET"
```

Set a real `CRON_SECRET`. Each call runs every job whose schedule came due since its last run. A slower tick still runs the hourly sweep; it just works the queue less often (2 images per tick). Check **Last Run** at `/admin/core/advanced/cron`. See [Cron over REST](/docs/dev/cron/rest-api) and [Node CRON adapter](/docs/dev/cron/node-cron).

## Edit ALT text through the API [#edit-alt-text-through-the-api]

The file ALT routes live in the `admin/files` module and use the `files` staff permissions:

| Route                              | Permission           | Purpose                                                                |
| :--------------------------------- | :------------------- | :--------------------------------------------------------------------- |
| `GET /admin/files/{id}/alt`        | `files:can_view`     | ALT per site language, with `origin` and `stale`.                      |
| `PUT /admin/files/{id}/alt`        | `files:can_edit_alt` | Set one language as a human text (`""` allowed).                       |
| `DELETE /admin/files/{id}/alt`     | `files:can_edit_alt` | Remove one language (`?languageCode=`), so the job may write it again. |
| `PUT /admin/files/{id}/alt-policy` | `files:can_edit_alt` | Set `automatic`, `manual` or `disabled`.                               |

```ts
await fetcher({
  plugin: '@vitnode/core',
  method: 'put',
  module: 'admin/files',
  path: '/{id}/alt',
  args: {
    params: { id: 42 },
    body: { languageCode: 'pl', text: 'Czerwony rower' },
  },
})
```

## React to new ALT text [#react-to-new-alt-text]

`files.alt.updated` fires when the job (`origin: "ai"`) or a person (`origin: "human"`) writes a file's default ALT:

```ts title="plugins/gallery/src/api/lib/events.ts"
import { buildEventListener } from '@vitnode/core/api/lib/events'

export const altUpdatedListener = buildEventListener({
  event: 'files.alt.updated',
  name: 'refresh-gallery-alt',
  handler: async (c, { fileId, languageCodes, origin }) => {
    await c
      .get('log')
      .info(`ALT for file ${fileId} (${languageCodes.join(', ')}) by ${origin}`)
  },
})
```

See [Built-in events](/docs/dev/events/built-in-events#ai-events).

## Limits and gotchas [#limits-and-gotchas]

- **Images only.** The job reads `image/jpeg`, `image/png`, `image/gif` and `image/webp`. It never analyses other files.
- **Base language is English.** Other languages are translations of the English description.
- **Legacy `metadata.alt` is not migrated.** An ALT a plugin stored in the free-form `core_files.metadata` column has no language, and VitNode does not guess one. The job treats those images as missing ALT text. Copy such values into `core_files_alt` yourself with `PUT /admin/files/{id}/alt` if you know their language.
- **Cost.** The **Automatic ALT text** card on **Artificial Intelligence (AI) → Overview** shows images described, translations and the known cost per image and per translation.

## Learn more [#learn-more]

# Costs, Points & Budgets (/docs/dev/ai/costs-and-limits)

Every [AI action](/docs/dev/ai/actions) run is priced in **USD** and charged to the site's budget. Runs started by users are also charged in **AI points**. VitNode reserves the worst case before calling a provider, then settles the real cost afterwards. Users pay only for results they receive.

```text
1,000 input tokens  × $3  / 1M = $0.003
  200 output tokens × $15 / 1M = $0.003
                         total = $0.006  →  6 AI points
```

## Usage and cost of a call [#usage-and-cost-of-a-call]

Each provider call is stored with its token usage and its cost:

```ts
interface AiUsage {
  inputTokens: number | null
  outputTokens: number | null
  cacheReadTokens: number | null
  cacheWriteTokens: number | null
  reasoningTokens: number | null // already part of outputTokens
}

type AiCost =
  | { source: 'provider'; amountUsd: string }
  | { source: 'pricing'; amountUsd: string; pricingVersion: string }
  | { source: 'unknown'; amountUsd: null; reason: string }
```

Amounts are decimal strings with 12 decimal places, stored as `numeric(24, 12)` in PostgreSQL. Money never passes through JavaScript floats, so a thousand tiny calls add up exactly.

### Unknown is not zero [#unknown-is-not-zero]

`null` means "nobody told us". `0` means "we know it was zero". VitNode keeps them apart everywhere:

- A provider that does not report token usage gives `null` tokens and an `unknown` cost.
- A model without pricing gives an `unknown` cost, with the reason `"no pricing"`.
- An `unknown` cost is never shown or summed as `$0`. When it must be charged, it is charged as the **full reservation**: the most the call could have cost.

## How cost is resolved [#how-cost-is-resolved]

For every call, VitNode takes the first of these that is available:

1. **Provider-reported cost**: what the provider says it billed (AI Gateway, OpenRouter).
2. **Pricing**: token usage × the `pricing` of the model in `vitnode.api.config.ts`.
3. **Unknown**: never zero.

Each estimated call stores the pricing version it used (`config:<fingerprint>` of the price). Changing a price later never rewrites history.

## Model pricing [#model-pricing]

Every model sets its own price in `vitnode.api.config.ts`. It is the only place prices live. There is no price editor in the AdminCP and no automatic sync, so what you deploy is what VitNode charges. A price that isn't a decimal string stops the server at boot instead of quietly turning every cost into `unknown`.

```ts title="apps/api/src/vitnode.api.config.ts"
ai: {
  models: [
    {
      id: 'default',
      name: 'Claude Sonnet 5',
      model: 'anthropic/claude-sonnet-5',
      capabilities: ['text', 'image-input', 'structured-output', 'streaming'],
      // [!code ++:3]
      pricing: {
        rates: { inputPerMillion: '3', outputPerMillion: '15' },
      },
    },
  ],
},
```

Prices are USD **per one million tokens**, as decimal strings. The full shape:

```ts title="apps/api/src/vitnode.api.config.ts"
pricing: {
  rates: {
    inputPerMillion: '3',
    outputPerMillion: '15',
    cacheReadPerMillion: '0.30',
    cacheWritePerMillion: '3.75',
  },
  // [!code ++:6]
  tiers: [
    {
      aboveInputTokens: 200_000,
      rates: { inputPerMillion: '6', outputPerMillion: '22.5' },
    },
  ],
}
```

How the rates apply:

- **Cache tokens** are priced separately from uncached input. If a call reports cache tokens but the pricing has no cache rate, the cost becomes `unknown` rather than quietly cheaper.
- **Tiers** price long-context calls. When a call's input tokens exceed `aboveInputTokens`, the **whole call** uses that tier's rates. A tier's `rates` replace the base rates entirely, so repeat the cache prices inside the tier if the provider charges them.
- **Reasoning tokens** are already part of `outputTokens`. They are stored for display, never billed twice.
- **Flat units** (`perRequest`, `perImage`) are added on top of the token cost.

Here is a worked example with the pricing above, for 10,000 input tokens (2,000 cache reads, 1,000 cache writes) and 500 output tokens:

```text
7,000 uncached    × $3    / 1M = $0.021
2,000 cache read  × $0.30 / 1M = $0.0006
1,000 cache write × $3.75 / 1M = $0.00375
  500 output      × $15   / 1M = $0.0075
                         total = $0.03285  →  32.85 AI points
```

### Gateway vs direct pricing [#gateway-vs-direct-pricing]

`pricing` is the price **on this connection**. The AI Gateway and the direct provider are different connections, and they can bill differently. Set the price you actually pay.

When a provider changes its prices, update `pricing` and deploy. Runs already charged keep the price version they were charged at.

<Callout type="warn" title="Reported cost does not replace pricing under a cap">
  The reservation happens _before_ the call, so it can only use pricing. A
  gateway model that reports its cost but has no pricing at all is still refused
  with `AI_PRICING_MISSING` while a budget cap applies.
</Callout>

### Provider-reported cost [#provider-reported-cost]

Provider adapters read cost and request ids from a provider's response metadata. The AI Gateway and OpenRouter adapters are built in. Every other provider reports no cost, so pricing estimates it.

Add an adapter for another provider that reports its cost:

```ts title="apps/api/src/vitnode.api.config.ts"
import type { AiProviderAdapter } from '@vitnode/core/api/lib/ai/usage-cost'

import { decimalFromNumber } from '@vitnode/core/api/lib/ai/decimal'

const acmeAdapter: AiProviderAdapter = {
  id: 'acme',
  matches: (providerId) => providerId.startsWith('acme'),
  reportedCost: (metadata) => {
    const cost = metadata?.acme?.costUsd

return typeof cost === 'number' ? decimalFromNumber(cost) : null
  },
  requestId: ({ responseId }) => responseId ?? null,
}

export const vitNodeApiConfig = buildApiConfig({
  ai: {
    models: [/* ... */],
    providerAdapters: [acmeAdapter], // [!code ++]
  },
})
```

`matches()` receives the model's provider id: `"gateway"` for AI Gateway string ids, otherwise the SDK model's `provider`. Your adapters are checked before the built-in ones. An optional `lookupCost(requestId)` lets reconciliation ask for the billed amount later.

## Runs with several calls [#runs-with-several-calls]

One run can make several provider calls: a retry, a fallback model, or extra steps in a tool loop. Each one is stored as its own call with its own usage and cost.

The run's cost is the sum of its calls, computed once at settlement. It is **known** only when every call's cost is known. If any call is unknown, the run is unknown and is charged as described in [Who pays what](#who-pays-what).

## Reconciliation and adjustments [#reconciliation-and-adjustments]

Some providers report the billed amount only after the response. The AI Gateway, for example, can look a generation up by its id. Reconciliation revisits recent calls whose cost was estimated or unknown, asks the provider adapter's `lookupCost()`, and replaces the cost with the billed amount.

Every correction:

- writes an **audit row** with the previous cost, the new cost and the difference;
- happens **once** per call, so a second attempt changes nothing;
- moves the budgets by the **difference** only, so nothing is counted twice;
- adjusts the user's points only if the user was charged for that run.

A provider-reported cost is final and is never reconciled.

## AI points [#ai-points]

Users are charged in **AI points**, not dollars:

> **1 AI point = 0.001 USD** of API cost (conversion version 1)

| API cost | AI points |
| :------- | :-------- |
| $0.0003  | 0.3       |
| $0.003   | 3         |
| $0.012   | 12        |
| $1       | 1,000     |

- Points are an internal usage unit. Nobody buys them.
- Points keep full precision when stored and charged. The UI shows at most one decimal, and `<0.1` for tiny positive amounts.
- The conversion version is stored on every run. A future rate change becomes a new version, and old runs keep theirs.

## Budgets [#budgets]

Every run holds room in each budget that applies to it:

The system budget is an extra cap on background work, such as automatic image ALT text. System runs never touch a user's points or daily counters, but they still count against the site budget.

Budgets are calendar periods in the **site's time zone** (the default language's time zone). A monthly budget resets at local midnight on the 1st, wherever the server runs. Limit errors include `resetsAt`.

## Reservations [#reservations]

Before any provider call, VitNode **reserves** the most the run could possibly cost:

- every attempt (`1 + maxRetries`), every step (`maxSteps`) and the fallback model;
- each at the model's dearest input rate and the highest tier the input could reach;
- the full `maxOutputTokens` for every call;
- the prompt measured in UTF-8 bytes, plus `imageInputTokens` per image. A prompt never has more tokens than bytes.

The reservation is a conservative upper bound. Settlement charges the real cost and releases the rest.

How it stays correct with many API instances:

- Reserving is **one short database transaction**. It locks the budget rows, checks the rate, concurrency and every cap, then writes the run and its holds.
- Budget rows are always locked in the **same order** (by scope key), so two runs can never deadlock.
- **No transaction is open during the provider call.** A slow model never holds a database lock.
- Settlement is **idempotent**. A run settles exactly once, and a second settlement changes nothing.

## Who pays what [#who-pays-what]

**A user is charged only when a valid result is delivered.** When the provider fails, times out, or the answer is unusable, the site pays for whatever the provider may have billed. Reconciliation can correct an unknown charge later.

Runs whose process died stay `running` until their lease expires, which takes `timeoutMs` per possible attempt plus one minute. The `ai-maintenance` cron (every 10 minutes) then settles them as `uncertain`. The same cron reconciles costs and prunes history, so the host must run VitNode's cron. See [Cron](/docs/dev/cron).

## Role policies and user overrides [#role-policies-and-user-overrides]

Admins control who may use AI and how much in the AdminCP:

- **AI permissions per role**: on the **Artificial intelligence (AI)** tab of the role form, grant or deny each action permission, with an optional daily limit.
- **Monthly point policies per role**: on the same tab, set an allowance in points, or unlimited.
- **Default monthly points**: the site-wide allowance when no role policy gives more (**Artificial Intelligence (AI) → Overview → Settings**).
- **User overrides**: on the **AI access** card of a member's AdminCP page, block them, make them unlimited, or set their own allowance.

How multiple roles combine:

- **Any granting role grants.** A permission no role mentions falls back to the action's `defaultGranted`.
- **The largest allowance wins.** Allowances are never summed: a user in "Editors" (500 points) and "Moderators" (2,000 points) gets 2,000, not 2,500. The default monthly points act as a floor.
- **The largest daily limit wins** among granting roles. A granting role with no daily limit lifts the role limit, and the action's own daily limit applies.
- **Root roles** always have access, with no personal point cap.
- **A user override replaces** what the roles give. A blocked user cannot run any action.

<Callout type="warn" title="Users start with zero points">
  The default monthly points are `0`. Until an admin sets a role policy, an
  override or a higher default, only root roles can run priced user actions.
  Everyone else gets `AI_USER_LIMIT_REACHED`.
</Callout>

## Rate and concurrency limits [#rate-and-concurrency-limits]

VitNode checks both inside the reservation transaction, under the same locks as the budgets. Two requests from one user cannot both slip past the limit. A refused run fails with `AI_RATE_LIMITED` or `AI_CONCURRENCY_LIMITED` before any provider call.

## Missing pricing [#missing-pricing]

When a model has no effective pricing, VitNode cannot bound the run:

- **Under any money cap**, the run is refused with `AI_PRICING_MISSING` before any provider call. The site budget, the system budget and the user's points all count as money caps.
- **Daily run counts** need no pricing.
- **With no cap at all**, the run goes ahead. Its cost is recorded as `unknown` and counted among unknown costs in the AdminCP.

Add `pricing` to the model in `vitnode.api.config.ts` to fix it.

## History and retention [#history-and-retention]

Every run and every provider call is stored in PostgreSQL: action, actor, model, prompt version, tokens, cost source, charges, status and error code.

History is kept for **365 days** by default (adjustable from 7 to 3,650). Pruning runs on its own schedule, independent of queue cleanup, and removes only settled runs and finished budget periods with nothing reserved.

## No Redis required [#no-redis-required]

Budgets, reservations, rate limits, concurrency and idempotency keys live in PostgreSQL and change inside transactions. AI accounting is correct with any number of API instances, with or without `REDIS_URL`.

## Learn more [#learn-more]

# AI in Fields & the Editor (/docs/dev/ai/fields-and-editor)

Give a Content Engine `text` or `textarea` field an `ai` option and the AdminCP form shows an **AI** button next to it. The button runs a registered [AI action](/docs/dev/ai/actions) with the other fields as input, shows the suggestion for review, and writes nothing until the editor accepts it.

```ts title="plugins/blog/src/content/post.ts"
excerpt: field.textarea({
  ai: {
    action: '@vitnode/blog:excerpt.generate',
    mode: 'suggestion',
    sourceFields: ['title', 'content'],
  },
  localized: true,
  nullable: true,
  maxLength: 300,
}),
```

You write no route, no button and no form code. Core provides all of it.

## Add AI to a field in your plugin [#add-ai-to-a-field-in-your-plugin]

The `@vitnode/example` plugin suggests an article teaser from its title and product code. Here is the whole feature.

<Steps>

<Step>

### Define the action [#define-the-action]

The action's input is **one string per source field, plus `locale`** for the language being edited. Match `inputSchema` to that shape.

```ts title="plugins/example/src/api/ai/actions.ts"
import { defineAiAction } from '@vitnode/core/api/lib/ai/action'
import { checkStaffPermission } from '@vitnode/core/api/lib/check-staff-permission'
import { z } from 'zod'

import { CONFIG_PLUGIN } from '@/const'
import { articleContentType } from '@/content/article'

export const articleExcerptAiAction = defineAiAction({
  id: 'article.excerpt',
  description: 'Suggests a teaser for an example article.',
  promptVersion: 1,
  permission: { key: 'article.excerpt', defaultGranted: true },
  requiredCapabilities: ['text'],
  defaults: {
    maxInputCharacters: 400,
    maxOutputTokens: 120,
    timeoutMs: 20_000,
  },
  // [!code ++:5]
  inputSchema: z.object({
    code: z.string().max(100),
    locale: z.string().min(2).max(16),
    title: z.string().min(1).max(200),
  }),
  output: 'text',
  outputSchema: z.string().min(1).max(500),
  parseText: (text) => text.trim().replace(/^["“](.*)["”]$/su, '$1'),
  buildPrompt: (input, { instructions }) => ({
    prompt: `Title: ${input.title}\nProduct code: ${input.code}`,
    system: [
      'You write a one-sentence teaser for an article in a demo catalogue.',
      `Write it in ${input.locale}, under 200 characters.`,
      'Answer with the teaser only, without quotes.',
      ...(instructions ? [instructions] : []),
    ].join('\n'),
  }),
  // The AI permission never replaces access to the content.
  authorize: async ({ c }) =>
    await checkStaffPermission(c, {
      module: articleContentType.permissionModule,
      permission: 'can_edit',
      plugin: CONFIG_PLUGIN.pluginId,
      type: 'admin',
    }),
})
```

The real file turns the locale code into a language name with `Intl.DisplayNames`, because models write better for "Polish" than for "pl".

</Step>

<Step>

### Register it [#register-it]

```ts title="plugins/example/src/config.api.ts"
export const exampleApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    aiActions: [articleExcerptAiAction], // [!code ++]
    modules: [adminModule /* ... */],
  })
```

</Step>

<Step>

### Point the field at it [#point-the-field-at-it]

Use the canonical key, `<pluginId>:<localId>`:

```ts title="plugins/example/src/content/article.ts"
excerpt: field.textarea({
  // [!code ++:5]
  ai: {
    action: '@vitnode/example:article.excerpt',
    mode: 'suggestion',
    sourceFields: ['title', 'code'],
  },
  maxLength: 500,
  nullable: true,
}),
```

</Step>

<Step>

### Give editors access [#give-editors-access]

The editor's role needs the action's permission and an AI points allowance. See [AI access](/docs/dev/ai/admin#ai-access). With `defaultGranted: true` the permission is on until a role says otherwise, but the default monthly points are `0`, so non-root editors still need an allowance.

</Step>

</Steps>

### The `ai` field option [#the-ai-field-option]

<TypeTable
  type={{
    action: {
      description: 'Canonical action key, `<pluginId>:<localId>`.',
      type: '`${string}:${string}`',
      required: true,
    },
    mode: {
      description: 'The editor previews the result and accepts or discards it.',
      type: '"suggestion"',
      required: true,
    },
    sourceFields: {
      description:
        'Fields the action reads, in the locale being edited. Each becomes a key of the input.',
      type: 'readonly string[]',
      required: true,
    },
  }}
/>

`ai` is plain JSON on the field definition, so it reaches the browser too. Nothing AI-specific is stored with the content.

### Mistakes fail early [#mistakes-fail-early]

- **When the content type is defined**, `defineContentType()` throws if the key is not `<pluginId>:<localId>`, `mode` is not `"suggestion"`, a source field does not exist, or the field lists itself as a source.
- **At boot**, VitNode throws if no installed plugin registers the action, or the action is system-only (`actors: ["system"]`).

The input shape is not checked at boot. A mismatch between `sourceFields` and `inputSchema` shows up as `AI_INVALID_INPUT` on the first click.

## What editors see [#what-editors-see]

The **AI** button appears only when the server says this admin may start the action: AI is on, the action is enabled, a configured model can run it, and their roles grant its permission.

1. **Generate** sends the source fields in the language being edited. It is disabled with _"Fill in title first"_ while a source field is empty.
2. The suggestion appears in a review panel: **Discard**, **Try again** or **Use suggestion**.
3. **Use suggestion** puts the text into the field. Only the edited language changes. Saving still goes through the normal form, validation and revisions.

The panel warns before stale text replaces anything:

- **The sources changed** since the suggestion was made: _"The text it was written from changed since. Try again for an up-to-date suggestion."_
- **The editor typed into the field** after asking: the accept button becomes **Replace my newer text**.

Accepting or discarding is recorded on the run for statistics only. It never changes what was charged. Each [error code](/docs/dev/ai/actions#error-codes) has its own message, such as _"The AI provider failed. Nothing was charged to you."_ or _"You reached today's limit for this AI feature."_

## Run actions from your own UI [#run-actions-from-your-own-ui]

The field button uses generic routes that run **any** registered user action. Your own AdminCP components can use them too:

| Route                                      | Session     | Purpose                                     |
| :----------------------------------------- | :---------- | :------------------------------------------ |
| `POST /admin/ai/assist`                    | AdminCP     | Run an action, JSON in, JSON out.           |
| `GET /admin/ai/assist/available`           | AdminCP     | Action keys this admin may start.           |
| `POST /admin/ai/assist/runs/{id}/feedback` | AdminCP     | Record `{ accepted }` for one of your runs. |
| `POST /ai/run`                             | Site member | Run an action, JSON in, JSON out.           |
| `GET /ai/available`                        | Site member | Action keys this member may start.          |
| `POST /ai/runs/{id}/feedback`              | Site member | Record `{ accepted }`.                      |

The body is `{ action, input, idempotencyKey?, resource?, sourceFingerprint? }`. It never carries a model, a price or an actor. The server decides those. There is no extra staff permission on these routes on purpose: the action's AI permission and its `authorize()` decide.

The browser helpers wrap them. The blog's pre-publication review is a complete example:

```tsx title="plugins/blog/src/views/admin/article/editor/ai-review.tsx"
import { useAvailableAiActions } from '@vitnode/core/components/ai/use-available-ai-actions'
import {
  aiErrorCodeOf,
  requestAiAssist,
} from '@vitnode/core/lib/ai/assist-client'

const { data: available = [] } = useAvailableAiActions('admin')
if (!available.includes('@vitnode/blog:article.review')) return null

try {
  const { output, runId } = await requestAiAssist({
    action: '@vitnode/blog:article.review',
    input: { content, excerpt, locale, title },
  })
} catch (error) {
  setError(aiErrorCodeOf(error)) // e.g. "AI_USER_LIMIT_REACHED"
}
```

`requestAiAssist()` calls `POST /admin/ai/assist` with a fresh idempotency key and throws an `AiRequestError` on failure. The available-actions list only decides which buttons to show. The server authorizes every run again.

## Quick Ask in the rich text editor [#quick-ask-in-the-rich-text-editor]

Quick Ask is the **Quick Ask (AI)** button in the Tiptap rich text editor toolbar. It works on the selection and the text around it:

<Callout type="warn" title="Off until an admin grants it">
  Both actions share the permission `@vitnode/core:editor.assist` with
  `defaultGranted: false`. Nobody but root sees Quick Ask until an admin allows
  it for a role in **Artificial Intelligence (AI) → Access & limits** and gives
  that role points.
</Callout>

How it behaves:

- **Bounded context.** It sends the selection (up to 8,000 characters) and up to 1,500 characters before and after it. It never sends the whole document.
- **Streamed and previewed.** The answer streams into a preview. **Stop** cancels it; a canceled run charges the member no points.
- **Cost shown first.** With a selection, the panel shows the reservation bound, not a price: _"One request costs at most N AI points - usually much less."_
- **Plain text only.** The answer becomes paragraphs and hard breaks. It is never parsed as HTML, so it cannot inject markup, links or scripts.
- **Stale selection.** If the selected text changed while the answer was written, **Replace selection** is disabled; **Insert below** still works.
- **One-step undo.** Applying is one editor transaction. The toast's **Undo** or Ctrl+Z restores the text exactly.
- **Nothing is saved** until the form is saved.
- **Content language.** It writes in the language of the field being edited (the multi-language tab), not the interface language.
- **Streaming models only.** Streamed runs use only models that declare the `streaming` capability; without one, Quick Ask fails with `AI_MODEL_INCOMPATIBLE`.

Quick Ask uses the AdminCP routes on `/admin` pages and the member routes everywhere else.

### Streaming and estimate routes [#streaming-and-estimate-routes]

The stream routes accept the same body as `/ai/run` and answer `application/x-ndjson`, one JSON object per line:

```text
{"t":"A tighter "}
{"t":"version of the paragraph."}
{"done":{"runId":812,"chargedPoints":"0.42","costKnown":true,"modelId":"default"}}
```

A failure after the stream started arrives as `{"e":{"code":"AI_TIMEOUT","message":"…"}}`. Limits and budgets are checked before the first byte, so refusals are ordinary JSON error responses. Only `text` actions stream.

`/estimate` answers `{ maxPoints, maxUsd }`: the most the run could cost, or `null` when no pricing bounds it.

Use the browser helpers from `@vitnode/core/lib/ai/stream-client` in your own editor tools:

```ts
import {
  aiAssistScope,
  streamAiAction,
} from '@vitnode/core/lib/ai/stream-client'

const controller = new AbortController()
const summary = await streamAiAction({
  action: '@vitnode/core:editor.selection.rewrite',
  input: { after, before, locale, operation: 'shorten', selection },
  onDelta: (delta) => setPreview((text) => text + delta),
  scope: aiAssistScope(), // "admin" on /admin pages, otherwise "user"
  signal: controller.signal, // controller.abort() stops paying
})
```

`estimateAiAction({ action, input, scope })` resolves to the maximum points as a string, or `null`. The editor-side helpers `takeQuickAskSnapshot()`, `isQuickAskStale()` and `applyQuickAskResult()` live in `@vitnode/core/components/tiptap/quick-ask/quick-ask-editor`.

## Rich-text translation keeps its structure [#rich-text-translation-keeps-its-structure]

Asking a model to "preserve the HTML" is not a guarantee. The blog's `field.translate` action checks it instead:

```ts title="plugins/blog/src/api/ai/actions.ts"
import { assertSameHtmlStructure } from '@vitnode/core/api/lib/ai/html-structure'

parseText: (text, input) => {
  if (input.format === 'text') return unquote(text)
  const translated = text.trim()
  assertSameHtmlStructure(input.text, translated) // [!code highlight]

return translated
},
```

`assertSameHtmlStructure(source, translated)` compares every tag in order, with its attributes. Text and the translatable attributes `alt`, `title`, `aria-label` and `placeholder` may change; tags, links and other attributes may not. A difference throws `HtmlStructureError`, the run fails with `AI_INVALID_OUTPUT`, and the editor is not charged.

`htmlStructureDifference()` returns the first difference as a string (or `null`) when you want to report it instead of throwing.

## Translation freshness [#translation-freshness]

For each translated field, VitNode stores a fingerprint of **the source text it was translated from** in `core_ai_translation_sources`. Comparing that fingerprint with the current source shows exactly which fields are outdated. VitNode never uses timestamps for this.

Use `useTranslationFreshness()` inside a Content Engine form:

```tsx title="plugins/blog/src/views/admin/article/editor/article-editor.tsx"
import {
  useContentForm,
  useContentFormValues,
  useTranslationFreshness,
} from '@vitnode/core/content/admin-form'

const { defaultLocale } = useContentForm()
const values = useContentFormValues()

const freshness = useTranslationFreshness({
  contentTypeId,
  fields: ['title', 'content', 'excerpt'],
  itemId, // undefined while creating
  source: defaultLocale ?? 'en',
  values,
})

freshness.freshnessOf('pl') // { title: 'fresh', content: 'outdated', excerpt: 'missing' }
freshness.outdatedFields('pl') // ['content']
freshness.editedByPerson('pl', 'content') // true when a person changed the AI text

// After placing an AI translation into the form:
freshness.rememberAiTranslation('pl', 'content')
// When a person confirms the translations still match the source:
freshness.markReviewed('pl', freshness.outdatedFields('pl'))
```

`rememberAiTranslation()` and `markReviewed()` record nothing immediately. They are written when the form is saved, through the form's `onSaved` hook, so a record always describes text that was actually kept. Your own form code can subscribe the same way: `useContentForm().onSaved?.(async ({ itemId }) => { … })` returns an unsubscribe function.

The blog uses this to show which languages are outdated, to update only outdated fields that no person edited, and to let an editor mark a translation as reviewed.

The records are read and written with `GET` and `PUT /admin/ai/translation-sources`. Both require `can_edit` on the content type's own permission module.

## Pre-publication review [#pre-publication-review]

The blog's `@vitnode/blog:article.review` action is an optional read-through in the article editor's side panel. It is an `output: "object"` action, so it needs a `structured-output` model. It returns:

```ts
{
  summary: string,
  suggestions: Array<{
    area: 'clarity' | 'completeness' | 'structure' | 'tone',
    message: string,
    priority: 'high' | 'low',
  }>, // at most 8
}
```

- It **never verifies facts**. The prompt forbids judging whether facts are true, because the model has nothing to check them against.
- It **never gates publishing**. The deterministic readiness checks decide; publishing works the same with or without a review.

It is a good template for structured, advisory AI in your own plugin.

## Learn more [#learn-more]

# AI Setup (/docs/dev/ai)

VitNode integrates the [Vercel AI SDK](https://ai-sdk.dev). Register models in `vitnode.api.config.ts` once, then use them inside any API handler via `c.get("ai")`.

## Quick start [#quick-start]

### 1. Configure models in the API config [#1-configure-models-in-the-api-config]

A model can be an AI Gateway id string or a direct provider instance:

```ts title="apps/api/src/vitnode.api.config.ts"
import { openai } from '@ai-sdk/openai'
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:13]
  ai: {
    models: [
      {
        id: 'default',
        name: 'GPT-4o Mini',
        model: openai('gpt-4o-mini'),
        capabilities: ['text', 'structured-output', 'streaming'],
        pricing: {
          rates: { inputPerMillion: '0.15', outputPerMillion: '0.60' },
        },
      },
    ],
  },
})
```

Set `OPENAI_API_KEY` in your `.env` file.

`capabilities` and `pricing` are optional, but [AI actions](/docs/dev/ai/actions) rely on them: capabilities decide which model can run an action, and pricing turns token usage into money. See [Model capabilities](#model-capabilities) and [Costs, Points & Budgets](/docs/dev/ai/costs-and-limits).

---

### 2. Use it in a route handler [#2-use-it-in-a-route-handler]

For user-facing features, run a registered [AI action](/docs/dev/ai/actions). It checks permissions, limits and budgets, and records the cost:

```ts
handler: async (c) => {
  // [!code ++:4]
  const { output } = await c.get('ai').run({
    action: EXCERPT_AI_ACTION,
    input: c.req.valid('json'),
  })

return c.json({ text: output })
}
```

For internal tooling, you can also resolve the raw model and call the SDK directly. See [AI Usage](/docs/dev/ai/usage).

---

## Model capabilities [#model-capabilities]

A capability says what a configured language model can do. VitNode never guesses it from the model's name. A model without `capabilities` is treated as `["text"]`.

Every [AI action](/docs/dev/ai/actions) declares the capabilities it needs. When a run starts, VitNode picks the first configured model that has all of them. If no model fits, the run fails with `AI_MODEL_INCOMPATIBLE` before anything is sent to a provider.

<Callout type="warn" title="Vision is not image generation">
  `image-input` means the model can _read_ images, which features such as image
  ALT text need. Generating images is a different thing: register those models
  under `imageModels` and resolve them with `c.get("ai").imageModel()`. Add
  `image-input` only to models whose provider docs say they accept images.
  Otherwise VitNode keeps images away from them.
</Callout>

---

## Model pricing [#model-pricing]

`pricing` is what the model costs **on this connection**, in USD per one million tokens. Prices are decimal strings, so money never goes through floating point:

```ts title="apps/api/src/vitnode.api.config.ts"
{
  id: 'default',
  name: 'Claude Sonnet',
  model: anthropic('claude-sonnet-4-5'),
  capabilities: ['text', 'image-input', 'structured-output', 'streaming'],
  // [!code ++:8]
  pricing: {
    rates: {
      inputPerMillion: '3',
      outputPerMillion: '15',
      cacheReadPerMillion: '0.30',
      cacheWritePerMillion: '3.75',
    },
  },
}
```

Prices live only in this config. The AdminCP has no price editor, so a price change is a code change you deploy. A malformed price stops the server at boot.

Without pricing, a call's cost stays **unknown**, never zero. Under a budget cap, a model with no pricing is refused with `AI_PRICING_MISSING`. Tiers, flat fees and gateway vs direct pricing are covered in [Costs, Points & Budgets](/docs/dev/ai/costs-and-limits#model-pricing).

### Model options [#model-options]

`ai` also accepts `providerAdapters`: readers for providers that report their own cost. The AI Gateway and OpenRouter readers are built in. See [Provider-reported cost](/docs/dev/ai/costs-and-limits#provider-reported-cost).

---

## Multiple models & embeddings [#multiple-models--embeddings]

Configure dedicated models for fast completions, reasoning, and vector embeddings:

```ts title="apps/api/src/vitnode.api.config.ts"
ai: {
  models: [
    {
      id: 'default',
      name: 'GPT-4o Mini',
      model: openai('gpt-4o-mini'),
      capabilities: ['text', 'structured-output', 'streaming'],
    },
    {
      id: 'reasoning',
      name: 'Claude Sonnet',
      model: 'anthropic/claude-sonnet-5', // AI Gateway id
      capabilities: ['text', 'image-input', 'structured-output', 'streaming'],
    },
  ],
  embeddingModels: [
    { id: 'default', name: 'Text Embedding 3', model: openai.embedding('text-embedding-3-small') },
  ],
}
```

Resolve specific models by ID:

```ts
const smartModel = c.get('ai').model('reasoning')
const embedModel = c.get('ai').embeddingModel()
const capabilities = c.get('ai').capabilities('reasoning') // ['text', 'image-input', ...]
```

`model()`, `embeddingModel()`, `imageModel()` and `models()` work as before. Admins can assign a different model (and a fallback) to each action in the AdminCP; an assigned model that lacks a required capability is refused.

---

## Reading the model list in the browser [#reading-the-model-list-in-the-browser]

Provider instances, API keys and prices stay on the server. `c.get("ai").models()` returns only the public half of each entry:

The middleware route publishes this list, and the browser reads it with
[`useMiddlewareConfigQuery()`](/docs/dev/fetcher#deployment-configuration):

```tsx title="plugins/writer/src/pages/model-picker.tsx"
import { useMiddlewareConfigQuery } from '@vitnode/core/tanstack/auth'

export const ModelPicker = () => {
  // [!code ++:1]
  const { data } = useMiddlewareConfigQuery()

if (data.ai.models.length === 0) return <p>AI is not configured.</p>

return (
    <select className="w-full">
      {data.ai.models.map((model) => (
        <option key={model.id} value={model.id}>
          {model.name}
        </option>
      ))}
    </select>
  )
}
```

The first entry is the default, which `c.get("ai").model()` resolves when a
handler gets no id. The list is empty when no `ai.models` are configured, so
a picker can hide itself instead of offering nothing.

## Learn more [#learn-more]

# AI Usage (/docs/dev/ai/usage)

VitNode uses the [Vercel AI SDK](https://ai-sdk.dev). Resolve a model from `c.get("ai")` and call the native SDK functions with it.

<Callout
  type="warn"
  title="Building a feature users can trigger? Use an AI action"
>
  Calling `generateText` with `c.get("ai").model()` bypasses permissions,
  budgets, AI points and run history. Nobody watches the bill until it arrives.
  For user-facing features, define an [AI action](/docs/dev/ai/actions) and run
  it with `c.get("ai").run()`. Keep direct SDK calls for internal tooling you
  fully control.
</Callout>

## Model resolvers [#model-resolvers]

---

## 1. Text generation [#1-text-generation]

Generate text in a Hono API route:

```ts title="plugins/blog/src/api/modules/posts/routes/summarize.route.ts"
import { buildRoute } from '@vitnode/core/api/lib/route'
import { generateText } from 'ai'
import { z } from 'zod'

export const summarizeRoute = buildRoute({
  pluginId: 'blog',
  route: {
    method: 'post',
    path: '/summarize',
    request: {
      body: {
        content: {
          'application/json': { schema: z.object({ text: z.string().min(1) }) },
        },
      },
    },
    responses: {
      200: { description: 'Text summary' },
    },
  },
  handler: async (c) => {
    const { text } = c.req.valid('json')

// [!code ++:6]
    const { text: summary } = await generateText({
      model: c.get('ai').model(),
      system: 'You are a concise summary assistant.',
      prompt: `Summarize the following content:

${text}`,
    })

return c.json({ summary })
  },
})
```

---

## 2. Streaming responses [#2-streaming-responses]

Stream the model's answer to the client as it arrives:

```ts
import { streamText } from 'ai'

handler: async (c) => {
  const result = streamText({
    model: c.get('ai').model(),
    prompt: 'Write an introduction to WebSockets.',
  })

// [!code ++:1]
  return result.toDataStreamResponse()
}
```

---

## 3. Structured output (`generateObject`) [#3-structured-output-generateobject]

Get typed JSON back from the model, shaped by a Zod schema:

```ts
import { generateObject } from 'ai'
import { z } from 'zod'

const postMetadataSchema = z.object({
  title: z.string(),
  tags: z.array(z.string()),
  estimatedReadingMinutes: z.number(),
})

// [!code ++:6]
const { object } = await generateObject({
  model: c.get('ai').model(),
  schema: postMetadataSchema,
  prompt: 'Generate SEO metadata for an article on Postgres indexing.',
})
```

---

## 4. Generating embeddings [#4-generating-embeddings]

Turn text into a vector embedding for semantic search:

```ts
import { embed } from 'ai'

// [!code ++:4]
const { embedding } = await embed({
  model: c.get('ai').embeddingModel(),
  value: 'How to configure Redis caching in VitNode',
})
```

## Learn more [#learn-more]

# Architecture (/docs/dev/architecture)

VitNode separates concerns between two core layers:

1. **TanStack Start**: Frontend UI, SSR, isomorphic routing, and client caching.
2. **Hono API**: Backend routing, session management, staff permissions, and database operations.

{/* Image prompt: VitNode architectural flow diagram displaying TanStack Start (SSR, route loaders, TanStack Query) communicating across an HTTP/RPC boundary with Hono API (middleware, sessions, Drizzle ORM) and PostgreSQL/Redis storage. Dark theme, 1600x900. */}

## System Boundaries [#system-boundaries]

| Responsibility        | TanStack Start (Web App)                      | Hono (API)                                                      |
| :-------------------- | :-------------------------------------------- | :-------------------------------------------------------------- |
| **Routing**           | Page URLs, dynamic parameters, nested layouts | REST/RPC endpoints under `/api/*`                               |
| **Data Fetching**     | Route loaders and the universal `fetcher`     | Query execution via Drizzle ORM                                 |
| **State & Cache**     | TanStack Query client cache                   | Redis domain cache & database storage                           |
| **Security Boundary** | UI guards (redirecting unauthenticated users) | **Enforces authentication, permissions, CSRF, and rate limits** |

<Callout type="warn" title="Security Boundary">
  Route guards (`beforeLoad`) enhance UX by redirecting visitors early, but the
  Hono API is the true security boundary. All private endpoints strictly verify
  cookies and permissions on every request.
</Callout>

---

## End-to-End Request Flow [#end-to-end-request-flow]

When a user visits a page (e.g. `/blog`):

---

## The Request Pipeline [#the-request-pipeline]

Before route matching, every request passes through the middleware
`createVitNodeStart` installs - in this order, and an app cannot get in front of
any of it:

`/api/*` reaches the same middleware and passes through untouched - no redirect,
no rewrite, no cache directive - so the Hono bridge sees the request exactly as
the client sent it and keeps its own caching policy. See
[Configuration](/docs/dev/configuration).

---

## Plugin System Architecture [#plugin-system-architecture]

VitNode is built around modular plugins located in `plugins/*`:

- **Independent Packages**: Plugins compile to their own `dist/` with isolated dependencies.
- **Unified Manifest**: Routes, AdminCP navigation, and database models are registered declaratively.
- **Zero Overhead**: Inactive plugins contribute no code or overhead to production bundles.

## Learn More [#learn-more]

# Cache API data (/docs/dev/cache/api)

`c.get("cache")` stores values in Redis from inside a Hono route handler. Use it for reads that are slow and give the same answer to many visitors, such as counts over a large table or a computed summary. Without Redis, every call runs your loader directly, so the same code works with and without it.

## Before you begin [#before-you-begin]

Connect Redis in `vitnode.api.config.ts` as described in [Redis](/docs/dev/advanced/redis). You can write the code below without Redis, but nothing is cached until it is connected.

### Wrap the slow read in `remember` [#wrap-the-slow-read-in-remember]

In the route handler, pass `remember` a key, a time to live (TTL) in seconds, and a function that loads the value:

```ts title="plugins/site-notes/src/api/modules/notes/routes/stats.route.ts"
handler: async c => {
  // [!code ++:5]
  const stats = await c.get('cache').remember(
    'notes:stats',
    60 * 5,
    async () => await countNotesByAuthor(c),
  )

return c.json(stats)
},
```

`countNotesByAuthor` stands for your existing database query. On a hit, `remember` returns the stored value and skips the query. On a miss, it runs the query, stores the result for five minutes and returns it.

Keys are prefixed with the plugin that owns the route. `notes:stats` is stored as `vitnode:cache:@acme/site-notes:notes:stats`, so it cannot collide with another plugin's key. Values are stored as JSON, so a `Date` comes back as a string.

</Step>
<Step>

### Delete the key when the data changes [#delete-the-key-when-the-data-changes]

In every route that changes notes, delete the key after the write succeeds:

```ts title="plugins/site-notes/src/api/modules/notes/routes/create.route.ts"
handler: async c => {
  const note = await createNote(c, c.req.valid('json'))
  await c.get('cache').delete('notes:stats') // [!code ++]

return c.json(note, 201)
},
```

The TTL is a safety net, not the invalidation. Without `delete`, visitors see outdated stats for up to five minutes after every write. `delete` also accepts an array of keys.

</Step>
</Steps>

<Callout type="warn" title="The API cache is shared by every visitor">
  A key such as `notes:stats` returns the same value to everyone. For data that
  depends on who is asking, put the user ID in the key, for example
  `notes:stats:${userId}`, or do not cache it.
</Callout>

`remember` treats a stored `null` as a miss, so a loader that returns `null` runs on every call. If an empty answer is expensive to compute, return an object such as `{ stats: null }` instead.

## Check the result [#check-the-result]

1. Open **AdminCP → System → Integrations** (`/admin/core/system/integrations`). The Redis card shows **Active** when Redis is connected. **Needs attention** means it is configured but unreachable.
2. Call the stats route, then list your plugin's keys:

```bash
   redis-cli --scan --pattern 'vitnode:cache:@acme/site-notes:*'
   ```

The output includes `vitnode:cache:@acme/site-notes:notes:stats`. Calling the route again within five minutes does not run `countNotesByAuthor`.

3. Create a note and run the same command. The key is gone until the next call to the stats route.

For every method, including `get`, `set`, `flush` and locks, see the [Cache reference](/docs/dev/cache/reference).

# Cache app data (/docs/dev/cache/app)

The app cache in VitNode is TanStack Query. A plugin route's loader fills a query entry during SSR or navigation, the page reads that same entry without another request, and a write invalidates it so the next read is fresh.

This guide builds a notes list for an `@acme/site-notes` plugin with a `notes` API module. How the API call itself works is covered in [Data fetching](/docs/dev/fetcher).

### Define the query once [#define-the-query-once]

Create one `queryOptions` helper for the list. The loader, the page and the mutation all use it, so they always agree on the key.

```ts title="plugins/site-notes/src/features/notes/notes-query.ts"
import { queryOptions } from '@tanstack/react-query'
import { fetcher } from '@vitnode/core/tanstack/fetcher'

export const notesQueryKey = ['@acme/site-notes', 'notes'] as const

export const notesQuery = () =>
  queryOptions({
    queryKey: notesQueryKey,
    queryFn: async () => {
      const response = await fetcher({
        plugin: '@acme/site-notes',
        method: 'get',
        module: 'notes',
        path: '/',
      })

if (response.status !== 200) {
        throw new Error(`Loading notes answered ${response.status}.`)
      }

return await response.json()
    },
  })
```

Start every key with your plugin ID. `invalidateQueries` matches keys by prefix, so a generic first segment such as `'notes'` would let one plugin invalidate another plugin's data.

</Step>
<Step>

### Warm the query in the route loader [#warm-the-query-in-the-route-loader]

Create the page with `defineRoute` from `@vitnode/core/tanstack/plugin-routes`. Its loader context includes `queryClient`. The framework-neutral `definePluginRoute` from `@vitnode/core/routing` only receives `locale`.

```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
import { useSuspenseQuery } from '@tanstack/react-query'
import { defineRoute } from '@vitnode/core/tanstack/plugin-routes'

import { notesQuery } from '../features/notes/notes-query'

export const route = defineRoute({
  load: async ({ context }) => {
    await context.queryClient.query({ ...notesQuery(), staleTime: 'static' }) // [!code ++]
  },
})

const NotesPage = () => {
  const { data: notes } = useSuspenseQuery(notesQuery())

return (
    <ul className="flex flex-col gap-2">
      {notes.map((note) => (
        <li key={note.id}>{note.title}</li>
      ))}
    </ul>
  )
}

export default NotesPage
```

`staleTime: 'static'` makes the loader reuse an entry that is already cached instead of fetching again on every navigation. The page reads the entry the loader just filled, so it renders without suspending.

</Step>
<Step>

### Invalidate the query after a write [#invalidate-the-query-after-a-write]

VitNode's query client does not refetch when a component mounts or the tab regains focus. A cached list stays as it is until your code invalidates it, so invalidate it in every mutation that changes notes:

```ts title="plugins/site-notes/src/features/notes/use-create-note.ts"
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { fetcher } from '@vitnode/core/tanstack/fetcher'
import { toast } from 'sonner'

import { notesQueryKey } from './notes-query'

export const useCreateNote = () => {
  const queryClient = useQueryClient()

return useMutation({
    mutationFn: async (title: string) => {
      const response = await fetcher({
        plugin: '@acme/site-notes',
        method: 'post',
        module: 'notes',
        path: '/',
        args: { body: { title } },
      })

if (response.status !== 201) {
        throw new Error(`Creating a note answered ${response.status}.`)
      }
    },
    onSuccess: async () => {
      await queryClient.invalidateQueries({ queryKey: notesQueryKey }) // [!code ++]
      toast.success('Note created', {
        description: 'It now appears in the notes list.',
      })
    },
  })
}
```

Invalidate the narrowest key that covers everything the write could change. For a list with paging or sorting, that is the list's root key: the changed row may have moved to a different page.

</Step>
</Steps>

<Callout type="warn" title="Put the user ID in per-user keys">
  For data that belongs to one signed-in user, such as drafts or settings, add
  the user ID to the query key. Otherwise, signing out and back in as someone
  else in the same tab can show the previous account's cached data.
</Callout>

## Check the result [#check-the-result]

1. Open the notes page with the browser's Network tab open. The list renders without a browser request for notes, because the loader filled the cache during SSR.
2. Navigate to another page and back with a link. No new request for notes is sent.
3. Create a note. You see one `POST` request, then one `GET` request that refetches the list, and the new note appears.

To cache the database work behind the `notes` endpoint as well, continue with [Cache API data](/docs/dev/cache/api).

# Cache (/docs/dev/cache)

VitNode caches in three places. The app keeps API responses in TanStack Query, so a page never asks for something it already has. The API keeps expensive results in Redis through `c.get("cache")`, so a slow query runs once for everyone. The page cache stores the rendered HTML of public pages, so an article renders once for all its visitors. All three are opt-in: nothing is cached until your code asks for it.

## Pick a layer [#pick-a-layer]

| You want to                                                     | Use                        | Guide                                        |
| --------------------------------------------------------------- | -------------------------- | -------------------------------------------- |
| Render SSR data without refetching it, and skip repeat requests | App cache (TanStack Query) | [Cache app data](/docs/dev/cache/app)        |
| Stop running the same slow database query for every visitor     | API cache (Redis)          | [Cache API data](/docs/dev/cache/api)        |
| Look up `remember`, `delete`, `flush` and the other methods     | API cache (Redis)          | [Cache reference](/docs/dev/cache/reference) |
| Render a public page once and send that HTML to every visitor   | Page cache                 | [Cache server-rendered pages](/docs/dev/cache/pages) |

Most features use both. The API caches the expensive part once, and each visitor's app keeps its own copy of the response.

<Callout type="info" title="The fetcher never caches">
  [`fetcher()`](/docs/dev/fetcher) forwards the visitor's cookies, so a stored
  response could be one visitor's data served to another. That is why caching
  lives in the two layers above and not in the fetcher.
</Callout>

Content Engine public reads are not cached on the server. To cache them in your app or a separate front end, see [Content Engine caching](/docs/content-engine/caching).

# How cached pages stay fresh (/docs/dev/cache/pages-invalidation)

A cached page is one rendered copy of HTML that every visitor receives. This page explains how long that copy lives, what it may contain, and how a Content Engine change replaces it. To turn caching on, follow [Cache server-rendered pages](/docs/dev/cache/pages).

## TTL and stale-while-revalidate [#ttl-and-stale-while-revalidate]

A route policy has two windows. Take `{ maxAge: 300, staleWhileRevalidate: 60 }` on `/blog/:slug`, and an article first requested at 12:00:00:

| Request at  | What the visitor gets                                                                    | Header        |
| ----------- | ---------------------------------------------------------------------------------------- | ------------- |
| 12:00:00    | A fresh render, which is stored                                                          | `MISS`        |
| 12:03:00    | The stored copy, without rendering                                                       | `HIT`         |
| 12:05:30    | The stored copy right away, while a new render runs in the background and replaces it     | `STALE`       |
| 12:05:31    | The new copy                                                                             | `HIT`         |
| after 12:06 | If nobody asked during the stale window, the visitor waits for a fresh render            | `MISS`        |

`maxAge` (the TTL) is how long a copy is fresh. `staleWhileRevalidate` is a fixed extra window, never an open-ended one: after it, nobody gets the old copy. Leave it out, or set it to `0`, and a visitor always waits for the fresh render once the TTL ends.

When many visitors ask for the same uncached page at once, the server renders it once and hands the result to all of them. That only covers requests reaching the same server process.

## Public HTML and personal UI [#public-html-and-personal-ui]

A cached page is rendered once for everybody, so VitNode renders it as a signed-out visitor sees it:

- The render receives no cookies and no `Authorization` header, whoever asked.
- The main layout skips the session, exactly as it does for a [prerendered page](/docs/dev/deployments/prerendering#what-a-prerendered-page-leaves-out). The browser loads the account menu and header navigation after the page arrives.
- A response is stored only when it is a `200` HTML page that sets no cookie and read no API response marked `private` or `no-store`. Everything else, including errors, redirects and `404`s, is sent once and forgotten.

Signed-in visitors receive the same stored copy and see their account menu once the browser loads it. When the shared copy does not exist, for example a moderator opening a hidden article that answers `404` to everyone else, VitNode renders the page again for that visitor's own request. That copy is marked `private, no-store` and never stored. The same happens when the shared render sets a cookie, so the visitor still receives it.

A page component on a cached route must not read the session on the server. Put anything that depends on who is looking, such as an edit button, in a component that loads its data in the browser.

## Content Engine invalidation [#content-engine-invalidation]

Content Engine routes label their responses with what they were built from: the record (`content:blog.post:item:3`) or, for a list, the whole content type (`content:blog.post:list`). While a cached page renders, VitNode collects the labels of every API response the page read, and stores them with the page.

Every content write announces itself after its database transaction has committed, and VitNode then invalidates the pages that read that record or listed its type. Publishing, editing, translating, hiding, deleting, scheduled publishing and the API all go through that one path, so no write can skip it. Whether a stale copy may still be served depends on the change:

| Change                                                                                          | Mode | What visitors see                                                            |
| ----------------------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------------------- |
| Edit, publish, unhide, restore, translation added, edited or published                          | Soft | One more visitor may get the previous copy while the new one renders.        |
| Hide, delete, unpublish, translation unpublished or deleted, slug changed                       | Hard | The old copy is never served again. The next request renders a fresh page.   |

A hard invalidation also covers a render that started before the change and finishes after it: that render is sent to the visitor who asked, but not stored. After a slug change, the old address answers with its `308` redirect straight away.

Invalidation is per record, not per language. Editing the Polish translation also refreshes the English page, which lists the Polish one in its `hreflang` links anyway. Scheduled publication and creating a draft are announced too, but a draft that nobody can see changes no page.

Data your page reads from your own API routes is invalidated only if you label it. Call `setPageCacheTags(c, [tag])` in the route and `invalidatePageCacheTags([tag], { mode })` after the write. See the [reference](/docs/dev/cache/pages-reference#label-and-invalidate-your-own-data). Anything unlabelled, such as settings, shows up when the TTL ends.

## From an edit to the public page [#from-an-edit-to-the-public-page]

With the blog's policy, an article saved in the AdminCP reaches visitors like this:

1. The save commits. The page is invalidated before the API answers the editor.
2. The next visitor gets the previous copy once (soft) or a fresh render (hard).
3. Every visitor after that gets the new version.

Visitors who navigate inside the app load the article from the public API, which is never cached on the server, so they see the new version at step 1.

## How it differs from other caches [#how-it-differs-from-other-caches]

| Cache                                                       | What it stores                                       | Shared by       | Expires                                  |
| ----------------------------------------------------------- | ---------------------------------------------------- | --------------- | ---------------------------------------- |
| [Prerendering](/docs/dev/deployments/prerendering)          | HTML files written by `vitnode build`                | Every visitor   | On the next build                        |
| Page cache (this page)                                      | HTML rendered on request                             | Every visitor   | TTL, stale window, content changes       |
| [App cache](/docs/dev/cache/app) (TanStack Query)           | API responses, in one browser tab                    | One visitor     | `staleTime`, `invalidateQueries`         |
| [API cache](/docs/dev/cache/api) (`c.get("cache")`)         | Values your API routes choose                        | Every request   | Its TTL, `delete` after a write          |

The page cache never stores API responses, and Content Engine public reads are not cached on the server, so a page rendered after an invalidation always reads the current database.

## Deployment limits [#deployment-limits]

- **Memory storage is per process.** Each process keeps its own copy, and a restart empties it. An invalidation only reaches the process that handled the write, which is fine for one process and wrong for several. Use `storage: "redis"` for more than one instance.
- **Separate API server.** In the default setup the API runs inside the web app and shares its cache. If your API runs in its own process, set `pageCache: { storage: "redis" }` in `buildApiConfig` too, with the same `REDIS_URL`, so writes reach the web app's cache.
- **Browsers and CDNs** receive `cache-control: no-cache` and an `ETag`. They may keep a copy but must ask the server each time, and the server answers `304 Not Modified` while the copy is current. No lifetime is advertised, because nothing could purge a CDN after a hide or a delete.
- **Clock skew.** A hard invalidation compares timestamps written by different servers. VitNode allows 2 seconds of difference between their clocks; keep them in sync with NTP.
- **Deployments.** Every build gets its own id in the cache key, so two versions running side by side never serve each other's HTML. Set `VITNODE_BUILD_ID` at build time, for example to a commit SHA, to choose the id yourself.
- **Storage outage.** If an invalidation cannot be written, VitNode does not report it as done. The write still succeeds, the failure is logged, scheduled publishing retries it, and the process that handled the write stops serving cached pages until the longest policy has expired. Other instances cannot be told and keep serving their copies until their TTL ends.

# Page cache reference (/docs/dev/cache/pages-reference)

Exact options and behavior of the page cache. For a walkthrough, see [Cache server-rendered pages](/docs/dev/cache/pages).

## Route `cache` option [#route-cache-option]

Accepted by `page()` and `index()` from `@vitnode/core/routing`.

| Name                   | Type     | Required | Default | Description                                                              |
| ---------------------- | -------- | -------- | ------- | ------------------------------------------------------------------------ |
| `maxAge`               | `number` | Yes      | -       | Seconds a stored page is fresh. Whole number from 1 to 31536000.         |
| `staleWhileRevalidate` | `number` | No       | `0`     | Extra seconds a stale page may be served while it re-renders. 0 to 31536000. |

`cache: false` declares that the route is not cached, which is also the default. The build fails with `invalid-cache` for a layout, an unknown key or a duration outside these ranges. A policy on an AdminCP route, an `/api` path or a route with `requires` (its own or a parent layout's) fails the build too.

## `vitNodeConfig.pageCache` [#vitnodeconfigpagecache]

Set in `buildConfig()` in the host app's `src/vitnode.config.ts`.

| Name      | Type                                         | Required | Default    | Description                                                                         |
| --------- | -------------------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------- |
| `enabled` | `boolean`                                    | No       | `true`     | `false` turns the cache off for every route. Development never caches either way.   |
| `storage` | `"memory" \| "redis"`                        | No       | `"memory"` | `"redis"` reads `REDIS_URL` when the server starts.                                 |
| `routes`  | `Record<string, PageCacheSetting>`           | No       | `{}`       | Per-route override, keyed by canonical path (`"/blog/:slug"`). `false` disables.    |

An override wins over the route's own `cache`, and may opt in one of the app's own route files. A key that matches no page route fails the build.

## `withPageCache(entry, options)` [#withpagecacheentry-options]

From `@vitnode/core/tanstack/page-cache/server`. Wraps a TanStack Start server entry and returns one with the same `fetch`.

| Name      | Type                  | Required | Description                                   |
| --------- | --------------------- | -------- | --------------------------------------------- |
| `buildId` | `string`              | Yes      | `pageCacheBuildId` from `src/page-cache.gen.ts` |
| `config`  | `VitNodeConfig`       | Yes      | The app's `vitNodeConfig`                     |
| `routes`  | `PageCacheRouteTable` | Yes      | `pageCacheRoutes` from `src/page-cache.gen.ts`  |

## Response headers [#response-headers]

| Header             | Value                                          | Meaning                                                              |
| ------------------ | ---------------------------------------------- | -------------------------------------------------------------------- |
| `x-vitnode-cache`  | `HIT`, `STALE`, `MISS`, `REVALIDATED`          | Served from the cache, stale while refreshing, rendered and stored, or re-rendered after expiry |
| `x-vitnode-cache`  | `BYPASS`                                       | The request skipped the cache, or the render could not be shared     |
| `cache-control`    | `no-cache`                                     | A shared page: browsers and CDNs must revalidate with the `ETag`     |
| `cache-control`    | `private, no-cache`                            | A shared page that also sets this visitor's locale cookie            |
| `cache-control`    | `private, no-store`                            | A page rendered for one visitor                                      |

Routes without a policy keep their usual headers and get no `x-vitnode-cache`.

## When a request skips the cache [#when-a-request-skips-the-cache]

A request on a cached route goes straight to the renderer when:

- its method is not `GET` or `HEAD` (`GET` and `HEAD` are cached separately);
- its query string has a parameter other than these analytics parameters, which are ignored: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `utm_id`, `fbclid`, `gclid`, `gbraid`, `wbraid`, `dclid`, `msclkid`, `yclid`, `twclid`, `ttclid`, `li_fat_id`, `igshid`, `mc_cid`, `mc_eid`, `_ga`, `_gl`. A `?preview=` link is one such parameter;
- the locale rules redirect it, for example `/en/blog/x` to `/blog/x`;
- the server could not write an invalidation and has paused the cache.

Entries are keyed by the request origin (scheme, host and port), the path, the method and the build id. Each language's URL and each domain therefore has its own entry.

## Label and invalidate your own data [#label-and-invalidate-your-own-data]

From `@vitnode/core/api/lib/page-cache`, for data a cached page reads from your own Hono routes.

| Function                                    | Returns                                   | Behavior                                                                                         |
| ------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `setPageCacheTags(c, tags)`                 | `void`                                    | Labels the response. A cached page that reads it during its render is stored with these tags.  |
| `invalidatePageCacheTags(tags, { mode })`   | `Promise<PageCacheInvalidationResult>`    | Invalidates every page stored with any of `tags`. `mode` is `"soft"` or `"hard"`.                |

```ts title="plugins/events/src/api/modules/events/routes/list.route.ts"
import { setPageCacheTags } from '@vitnode/core/api/lib/page-cache'

// in the handler, before returning the response
setPageCacheTags(c, ['events:list'])
```

```ts title="after the write commits"
import { invalidatePageCacheTags } from '@vitnode/core/api/lib/page-cache'

const result = await invalidatePageCacheTags(['events:list'], { mode: 'soft' })
if (result.status === 'failed') {
  await c.get('log').error('Cached event pages could not be invalidated.')
}
```

`status` is `"done"`, `"failed"` (with `error`) or `"not-configured"` when this process has no page cache, such as an API server without `pageCache` in `buildApiConfig`. Content Engine routes and writes already do this for you.

## `buildApiConfig({ pageCache })` [#buildapiconfig-pagecache-]

Only for an API that runs in its own process next to a web app using `storage: "redis"`.

| Name          | Type      | Required | Default | Description                                                            |
| ------------- | --------- | -------- | ------- | ---------------------------------------------------------------------- |
| `storage`     | `"redis"` | Yes      | -       | Writes invalidations to the Redis at `REDIS_URL`.                      |
| `maxLifetime` | `number`  | No       | `86400` | Longest `maxAge + staleWhileRevalidate` of any cached route, in seconds. |

# Cache server-rendered pages (/docs/dev/cache/pages)

The page cache stores the complete HTML a public page renders and sends the same copy to the next visitors. Use it for pages that look the same for everyone, such as a blog article, when they still have to be rendered on the server because their content lives in the database.

A route is never cached unless it asks to be. This guide caches the blog plugin's article page, `/blog/:slug`.

### Declare a cache policy on the route [#declare-a-cache-policy-on-the-route]

Add `cache` to the page in your plugin's `src/routes.ts`. Both durations are in seconds:

```ts title="plugins/blog/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/blog/:slug', {
    cache: { maxAge: 300, staleWhileRevalidate: 60 }, // [!code ++]
    component: lazy(() => import('./pages/post-page')),
    messages: ['@vitnode/blog.post'],
  }),
])
```

`maxAge: 300` keeps a rendered article fresh for 5 minutes. `staleWhileRevalidate: 60` adds one more minute in which a visitor may still get the previous copy while a fresh one renders in the background. [How cached pages stay fresh](/docs/dev/cache/pages-invalidation#ttl-and-stale-while-revalidate) walks through the timeline.

`index()` routes accept the same option. A layout, an AdminCP page and a route with `requires` cannot be cached, and the build fails if one declares a policy.

</Step>
<Step>

### Serve pages through the cache [#serve-pages-through-the-cache]

Wrap TanStack Start's server entry in your app's `src/server.ts`. Apps created with `create-vitnode-app` already have this file:

```ts title="apps/web/src/server.ts"
import handler from '@tanstack/react-start/server-entry'
import { withPageCache } from '@vitnode/core/tanstack/page-cache/server'

import { pageCacheBuildId, pageCacheRoutes } from './page-cache.gen'
import { vitNodeConfig } from './vitnode.config'

export default withPageCache(handler, {
  buildId: pageCacheBuildId,
  config: vitNodeConfig,
  routes: pageCacheRoutes,
})
```

`src/page-cache.gen.ts` is written by VitNode's Vite plugin on every `vitnode dev` and `vitnode build`. It holds every page route with the policy that applies to it, so commit it like the other `*.gen.ts` files.

</Step>
<Step>

### Choose the storage and override plugin policies [#choose-the-storage-and-override-plugin-policies]

Configure the cache once, in the host app. Every key is optional:

```ts title="apps/web/src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  // ...
  pageCache: {
    storage: 'redis', // reads REDIS_URL when the server starts
    routes: {
      '/blog/:slug': { maxAge: 600, staleWhileRevalidate: 120 },
      '/events/:slug': false,
    },
  },
})
```

| Storage    | Where entries live                     | Use it when                                                                                            |
| ---------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `"memory"` | Inside each server process (default)   | You run one server process. A restart empties the cache, and each process would keep its own copy.     |
| `"redis"`  | The Redis at the `REDIS_URL` variable  | You run more than one instance. All of them share entries, and an invalidation reaches every instance. |

`routes` keys are canonical route paths, the same spelling the route was declared with. A policy replaces the plugin's, `false` turns caching off for that route, and you can also opt in one of your app's own route files. A key that matches no page route fails the build. `enabled: false` turns the whole cache off.

The Redis URL stays in the runtime environment and never ends up in the build. If `storage` is `"redis"` and `REDIS_URL` is missing, the server logs an error and serves pages without caching them.

</Step>
<Step>

### Build and start the app [#build-and-start-the-app]

The cache only runs in production. Development always renders fresh, so an edit shows up on reload.

```bash tab="bun"
bun run build && bun start
```

```bash tab="pnpm"
pnpm build && pnpm start
```

```bash tab="npm"
npm run build && npm start
```

</Tabs>

The build's route summary shows the policy that each route actually got. See [Build and start for production](/docs/dev/cli/build#see-how-each-page-is-served).

</Step>
</Steps>

## Check the result [#check-the-result]

Request a published article twice and look at the `x-vitnode-cache` header:

```bash
curl -s -o /dev/null -D - http://localhost:3000/blog/hello-world | grep -i 'x-vitnode-cache\|cache-control'
curl -s -o /dev/null -D - http://localhost:3000/blog/hello-world | grep -i 'x-vitnode-cache\|cache-control'
```

```text
cache-control: no-cache
x-vitnode-cache: MISS
cache-control: no-cache
x-vitnode-cache: HIT
```

The first request rendered the page. The second was answered from the cache without rendering. Edit the article in the AdminCP and request it again: you get `STALE` once, then the new text. Hide it and the next request answers `404` immediately.

`BYPASS` means the request skipped the cache, for example because of a `?preview=` link or another query parameter. The [reference](/docs/dev/cache/pages-reference#when-a-request-skips-the-cache) lists every reason.

## Related [#related]

- [How cached pages stay fresh](/docs/dev/cache/pages-invalidation)
- [Page cache reference](/docs/dev/cache/pages-reference)
- [Prerender static pages](/docs/dev/deployments/prerendering)

# Cache reference (/docs/dev/cache/reference)

`c.get("cache")` is available in every Hono route handler. It stores JSON values in Redis under a per-plugin prefix and does nothing when Redis is not configured. For a step-by-step example, see [Cache API data](/docs/dev/cache/api).

## Methods [#methods]

| Method                                 | Returns                                                | Behavior                                                                                                                       |
| -------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `get<T>(key)`                          | `Promise<T \| null>`                                   | Reads and parses a value. Returns `null` on a miss, on a Redis error, or without Redis.                                        |
| `set<T>(key, value, ttlSeconds?)`      | `Promise<void>`                                        | Stores `value` as JSON. Without `ttlSeconds`, or with `0`, the key never expires.                                              |
| `has(key)`                             | `Promise<boolean>`                                     | Whether the key exists. `false` on a Redis error or without Redis.                                                             |
| `remember<T>(key, ttlSeconds, loader)` | `Promise<T>`                                           | Returns the cached value when `get` finds one. Otherwise runs `loader`, stores its result with `set` and returns it.           |
| `delete(key)`                          | `Promise<void>`                                        | Deletes one key, or every key in an array.                                                                                     |
| `flush()`                              | `Promise<void>`                                        | Deletes every key of the current plugin. Other plugins' keys and unrelated data in the same Redis instance are left untouched. |
| `acquireLock(key, ttlSeconds)`         | `Promise<boolean>`                                     | Takes a lock that expires after `ttlSeconds`. `true` when this call holds the lock, `false` when another caller does.          |
| `releaseLock(key)`                     | `Promise<void>`                                        | Releases a lock taken with `acquireLock`.                                                                                      |
| `status()`                             | `Promise<{ configured: boolean; connected: boolean }>` | Pings Redis. Both fields are `false` without Redis.                                                                            |

`getSystem`, `setSystem` and `deleteSystem` also exist. They write to a namespace shared with VitNode core, so plugins should use the plugin-scoped methods above.

## Keys [#keys]

| Method                                             | Stored as                             |
| -------------------------------------------------- | ------------------------------------- |
| `get`, `set`, `has`, `remember`, `delete`, `flush` | `vitnode:cache:{pluginId}:{key}`      |
| `acquireLock`, `releaseLock`                       | `vitnode:cache:__system__:lock:{key}` |

The plugin ID comes from the route that handles the request. Lock keys are not prefixed with it, so include your plugin ID in a lock key, for example `@acme/site-notes:rebuild-stats`.

## Serialization [#serialization]

Values go through `JSON.stringify` and `JSON.parse`:

- A `Date` comes back as an ISO string, and a `Map` or `Set` comes back as `{}`.
- `null` is stored, but `get` returns `null` for it, so `remember` treats it as a miss and runs the loader again.
- `undefined` is not stored.

## Without Redis and when Redis fails [#without-redis-and-when-redis-fails]

When the `redis` option in `vitnode.api.config.ts` is not set, every read misses, every write does nothing, and `remember` always runs its loader.

When Redis is configured but fails, the error never reaches your route. A failed read counts as a miss and a failed write is skipped. Commands fail immediately while Redis is unreachable instead of waiting in a queue, so an outage does not stall requests.

Locks behave differently, because a lock exists to stop work from running twice:

| Situation            | `acquireLock` returns |
| -------------------- | --------------------- |
| Redis connected      | `true` or `false`     |
| Redis not configured | `true`                |
| Redis error          | `false`               |

Without Redis, every caller gets the lock. If two instances must never run the same work at once, guard it in the database as well, for example with `FOR UPDATE SKIP LOCKED`.

# Cloudflare Turnstile (/docs/dev/captcha/cloudflare)

Turnstile is the provider to reach for first: a visible widget, no score to
tune, and a set of dummy keys that work on `localhost`. There is nothing to
install - the provider lives in core - so the whole job is two keys and one
config block.

## Quick start [#quick-start]

If you already have a site key and a secret key, this is the entire
integration.

```bash title=".env"
CLOUDFLARE_TURNSTILE_SITE_KEY=0x4AAAAAAA...
CLOUDFLARE_TURNSTILE_SECRET_KEY=0x4AAAAAAA...
```

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:5]
  captcha: {
    type: 'cloudflare_turnstile',
    siteKey: process.env.CLOUDFLARE_TURNSTILE_SITE_KEY,
    secretKey: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY,
  },
})
```

Restart the API and the widget appears on `/register`, and on
`/login/reset-password` on a deployment that has an
[email adapter](/docs/dev/email) to send the link with. The rest of this page is
how to get those two values.

An empty `secretKey` does not disable captcha - it breaks it. `captchaMiddleware`
steps aside only when the whole `captcha` block is missing, so a deployment with
the block and no keys **rejects** registration and password reset with `400`.
Gate the block on the environment variable:

```ts title="src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:7]
  captcha: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY
    ? {
        type: 'cloudflare_turnstile',
        siteKey: process.env.CLOUDFLARE_TURNSTILE_SITE_KEY,
        secretKey: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY,
      }
    : undefined,
})
```

</Callout>

## Create the widget [#create-the-widget]

### Sign in to Cloudflare [#sign-in-to-cloudflare]

Open the [Cloudflare dashboard](https://dash.cloudflare.com/) and sign in.

Turnstile is an independent product - Cloudflare's own words are that you can
use it "on any website, regardless of whether it is proxied through the
Cloudflare network" - so there is no DNS to move before you start.

</Step>
<Step>

### Open Turnstile [#open-turnstile]

Pick **Turnstile** in the account sidebar, below **WAF**.

</Step>
<Step>

### Add a widget [#add-a-widget]

Press **Add widget** and fill in three things, then **Create**:

| Field                   | What to put in it                                                        |
| ----------------------- | ------------------------------------------------------------------------ |
| **Widget name**         | Anything - it is internal. Your site's name is a fine answer.            |
| **Hostname management** | Every hostname you serve the form from, e.g. `your-domain.com`.          |
| **Widget mode**         | **Managed** unless you have a reason. All three modes work with VitNode. |

{/* Image prompt: The Cloudflare Turnstile "Add widget" form filled in with a widget name, one entry under Hostname management, and the "Managed" widget mode option selected out of Managed / Non-Interactive / Invisible, light theme, 1100x700. */}

</Step>
<Step>

### Copy the site key and the secret key [#copy-the-site-key-and-the-secret-key]

Cloudflare shows both immediately after the widget is created, and you can come
back to them from the widget's **Settings** tab at any time.

The **site key** is public - the API publishes it so the browser can load the
widget. The **secret key** is not: it is only ever sent from your API to
Cloudflare's `siteverify` endpoint.

{/* Image prompt: The Cloudflare Turnstile widget detail page showing the "Site Key" and "Secret Key" fields with copy buttons, values partially redacted, light theme, 1100x500. */}

</Step>
<Step>

### Set the environment variables [#set-the-environment-variables]

These names are not magic - they are whatever you read in your config on the
next step. What matters is that both are server-side variables, because the
secret key must never reach a browser bundle.

```bash title=".env"
CLOUDFLARE_TURNSTILE_SITE_KEY=0x4AAAAAAA... # [!code ++]
CLOUDFLARE_TURNSTILE_SECRET_KEY=0x4AAAAAAA... # [!code ++]
```

</Step>
<Step>

### Register the provider [#register-the-provider]

Add the `captcha` block to your API config with `type: 'cloudflare_turnstile'`.

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

The config is evaluated when the process boots, so restart the API rather than
waiting for a hot reload to notice.

</Step>
<Step>

### Verify it works [#verify-it-works]

Ask the API what it thinks it has configured. The site key comes back on the
public middleware route:

```bash
curl http://localhost:3000/api/@vitnode/core/middleware
# {"isEmail":false,"sso":[],"captcha":{"siteKey":"0x4AAAAAAA...","type":"cloudflare_turnstile"}}
```

Then open `/register`. A Turnstile widget renders just above the **Register**
button, and the button stays disabled until the widget reports success.

The AdminCP confirms it from the other side: **AdminCP → System →
Integrations** (`/admin/core/system/integrations`) shows the **Captcha** card as
_Active_, with **Cloudflare Turnstile** underneath.

</Step>
</Steps>

## Test keys for local development [#test-keys-for-local-development]

Cloudflare publishes dummy keys that work on any hostname, `localhost`
included. Use them while you are wiring the form up, and to reproduce failures
on purpose.

The two halves are independent: a site key decides what the widget does in the
browser, a secret key decides what `siteverify` answers. Pick one of each.

### Test site keys [#test-site-keys]

| Site key                   | Widget    | What it does                    |
| -------------------------- | --------- | ------------------------------- |
| `1x00000000000000000000AA` | Visible   | Always passes                   |
| `2x00000000000000000000AB` | Visible   | Always fails                    |
| `1x00000000000000000000BB` | Invisible | Always passes                   |
| `2x00000000000000000000BB` | Invisible | Always fails                    |
| `3x00000000000000000000FF` | Visible   | Forces an interactive challenge |

### Test secret keys [#test-secret-keys]

| Secret key                            | What `siteverify` answers |
| ------------------------------------- | ------------------------- |
| `1x0000000000000000000000000000000AA` | Always passes             |
| `2x0000000000000000000000000000000AA` | Always fails              |
| `3x0000000000000000000000000000000AA` | `token already spent`     |

A test site key mints the token `XXXX.DUMMY.TOKEN.XXXX`, which a real secret key
rejects - so mixing a dummy site key with a production secret is its own kind of
`400`.

All of them come from
[Cloudflare's testing reference](https://developers.cloudflare.com/turnstile/troubleshooting/testing/),
which is also where the failure modes each one reproduces are spelled out.

## Widget modes [#widget-modes]

All three of Cloudflare's modes work, because VitNode renders the widget through
`turnstile.render` and waits for its callback either way.

| Mode                | What the visitor sees                      | Submit button                      |
| ------------------- | ------------------------------------------ | ---------------------------------- |
| **Managed**         | A checkbox, only when Cloudflare wants one | Unlocks when the widget calls back |
| **Non-Interactive** | A spinner, and never a checkbox            | Unlocks when the widget calls back |
| **Invisible**       | Nothing at all                             | Unlocks when the widget calls back |

Invisible mode is the one worth thinking twice about: the button is disabled for
a moment with nothing on screen explaining why.

The widget also inherits two things from the page it renders on - the visitor's
locale, and your site's resolved theme - so it follows the language switcher and
dark mode with no configuration of its own.

## Gotchas [#gotchas]

<Callout type="warn" title="A hostname you did not list fails silently">
  Turnstile refuses to render for a hostname that is not on the widget's list,
  and VitNode's submit button simply never unlocks. There is no toast and no
  server error, because nothing was ever submitted. Check the browser console
  for Turnstile's own message, then add the hostname - or switch to the test
  keys above while developing.
</Callout>

<Callout
  type="warn"
  title="Turnstile has no score, so there is nothing to tune"
>
  `siteverify` answers `success: true` or `success: false`, and VitNode scores
  that as `1` or `0`. How much the visitor is asked to do is the widget mode you
  picked in Cloudflare's dashboard; how suspicious they looked is Cloudflare's
  call, and it is not a number you get to see or set. If you want one to tune,
  that is [reCAPTCHA v3](/docs/dev/captcha/recaptcha).
</Callout>

<Callout type="info" title="Env changes need a restart">
  The API config reads `process.env` when the process starts, so a new key in
  `.env` only takes effect after you restart the dev server.
</Callout>

## Next [#next]

# Custom forms (/docs/dev/captcha/custom-adapter)

`AutoForm` handles captcha for you, and most of the time that is the end of it.
When you are rendering the form yourself - a hand-built `<form>`, a wizard, a
component that is not an `AutoForm` at all - `useCaptcha` is the same three
values `AutoForm` uses internally.

There is no captcha _adapter_ to write: the two providers live in core, and
`type` is a closed union. What this page is about is the client half.

## Quick start [#quick-start]

Three values, and a `<div>` for the widget to land in.

```tsx title="plugins/contact/src/views/contact/contact-form.tsx"
import type React from 'react'

import { useCaptcha } from '@vitnode/core/hooks/use-captcha' // [!code ++]
import { type MiddlewareConfig } from '@vitnode/core/tanstack/auth'

import { sendMessage } from './send-message'

export const ContactForm = ({
  captcha,
}: {
  captcha: MiddlewareConfig['captcha']
}) => {
  const { isReady, getToken, onReset } = useCaptcha(captcha) // [!code ++]

const onSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault()

await sendMessage({
      message: new FormData(event.currentTarget).get('message') as string,
      captchaToken: await getToken(), // [!code ++]
    })

onReset() // [!code ++]
  }

return (
    <form onSubmit={onSubmit}>
      <textarea name="message" />

{/* [!code ++] */}
      <div id="vitnode_captcha" />

<button disabled={!isReady} type="submit">
        Send
      </button>
    </form>
  )
}
```

On an installation with no captcha configured, `captcha` is `undefined`,
`getToken()` resolves to `''` and `isReady` flips to `true` as soon as the
hook's effect runs - so this is one code path, not two. `isReady` starts `false`
either way, which means a server-rendered submit button is disabled in the
initial HTML and unlocks on hydration.

## The hook [#the-hook]

```ts
const { isReady, getToken, onReset } = useCaptcha(captcha)
```

It takes exactly what the API publishes on
`GET /api/@vitnode/core/middleware`, so you pass the value through rather than
building it.

<TypeTable
  type={{
    captcha: {
      description:
        "The deployment's captcha configuration, or undefined when none is configured. Read it from useMiddlewareConfigQuery().",
      type: "{ siteKey: string; type: 'cloudflare_turnstile' | 'recaptcha_v3' } | undefined",
      required: true,
    },
    isReady: {
      description:
        'Whether a token can be obtained. Starts false and becomes true on mount when no captcha is configured, when a Turnstile widget has called back, or when the reCAPTCHA script has fired its load event. Wire it to your submit button.',
      type: 'boolean',
    },
    getToken: {
      description:
        "The solved token. Turnstile returns the one the widget already handed over; reCAPTCHA v3 mints a fresh one with grecaptcha.execute at call time. Resolves to '' when there is no captcha, and when the provider script never loaded.",
      type: '() => Promise<string>',
    },
    onReset: {
      description:
        'Clears the stored token and sets isReady back to false, and on Turnstile also calls turnstile.reset() so the widget re-arms. Call it after every submission so one token cannot be replayed.',
      type: '() => void',
    },
  }}
/>

## Wire it up [#wire-it-up]

### Gate the route [#gate-the-route]

Nothing on the client makes a route require a token - `withCaptcha: true` on the
route does, in a [plugin](/docs/dev/plugins/create) exactly as in core.

```ts title="plugins/my-plugin/src/api/modules/contact/routes/create.route.ts"
export const createContactRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: {
    method: 'post',
    path: '/',
    description: 'Send a message to the site owner',
    withCaptcha: true, // [!code ++]
    // ...
  },
  handler: async (c) => c.text('Message sent', 201),
})
```

</Step>
<Step>

### Read the deployment's config in the plugin screen [#read-the-deployments-config-in-the-plugin-screen]

The site key is public. A plugin page can read it with the shared TanStack Query
definition before rendering its form:

```tsx title="plugins/contact/src/pages/contact-page.tsx"
import { useMiddlewareConfigQuery } from '@vitnode/core/tanstack/auth'

import { ContactForm } from '../views/contact-form'

export const ContactScreen = () => {
  const { data: config } = useMiddlewareConfigQuery()

return <ContactForm captcha={config.captcha} />
}
```

</Step>
<Step>

### Mount the widget [#mount-the-widget]

`useCaptcha` finds its container by id, so the element has to exist in the DOM
before the provider script finishes loading. Render it unconditionally inside
the form:

```tsx
<div id="vitnode_captcha" />
```

Turnstile renders into it. reCAPTCHA v3 has nothing to draw, so the `<div>` is
harmless there and keeping it means the two providers swap without a code
change.

</Step>
<Step>

### Send the token [#send-the-token]

`captchaToken` is a first-class fetcher option, on both the universal fetcher
and the server one, and it spells the `x-vitnode-captcha-token` header for you. An
empty string sends no header at all.

```ts title="src/site/contact/send-message.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'

export const sendMessage = async ({
  captchaToken,
  ...body
}: {
  captchaToken: string
  message: string
}) =>
  await fetcher({
    plugin: '@vitnode/my-plugin',
    method: 'post',
    module: 'contact',
    path: '/',
    captchaToken, // [!code ++]
    args: { body },
  })
```

</Step>
<Step>

### Verify it is really gated [#verify-it-is-really-gated]

Call the route with no token. It answers `400` before your handler runs:

```bash
curl -i -X POST 'http://localhost:3000/api/@vitnode/my-plugin/contact' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Hello from curl"}'
```

```text
HTTP/1.1 400 Bad Request

Captcha token is required
```

Then open the form. With Turnstile the widget appears where you put the `<div>`
and the submit button unlocks on success; with reCAPTCHA v3 the button is
enabled from the start and the token is minted on submit.

</Step>
</Steps>

## Where the pieces live [#where-the-pieces-live]

A minimal captcha-gated feature is four files, and only one of them knows the
hook exists.

## Gotchas [#gotchas]

<Callout type="warn" title="One #vitnode_captcha per page">
  The container is found by id, so two captcha forms on one page fight over it:
  the challenge lands in whichever rendered first and the other's submit button
  never unlocks. Put the second form behind a dialog, a tab or its own route.
</Callout>

<Callout type="warn" title="The hook needs VitNode's providers above it">
  `useCaptcha` reads the visitor's locale and its error copy through `use-intl`,
  and the resolved theme through VitNode's `ThemeProvider` - the widget is
  rendered in both. `use-intl` throws without a provider, so the hook has to be
  mounted under `VitNodeRootProviders`, which every VitNode TanStack Start app
  already has above its route tree. Mount it outside and you get an intl context
  error, not a captcha.
</Callout>

<Callout type="warn" title="Call onReset(), but know what it costs on v3">
  Without it a visitor can submit the same token twice. With it, `isReady` goes
  back to `false` - and on reCAPTCHA v3 nothing sets it back to `true`, because
  there is no widget callback. A form that stays on screen after a failed
  submission ends up with a dead button until it remounts. Turnstile re-arms
  itself.
</Callout>

<Callout type="info" title="A missing script is not an error you can catch">
  If the provider's script is blocked, `getToken()` resolves to `''` rather than
  rejecting. Treat the API's `400` as the real signal - it is the only place
  that knows whether the token was any good.
</Callout>

## Next [#next]

# Captcha (/docs/dev/captcha)

VitNode provides built-in bot protection. When enabled in your API configuration, gated routes automatically demand and verify a challenge token before handler execution.

## Quick start [#quick-start]

### 1. Configure Captcha in API Config [#1-configure-captcha-in-api-config]

Add the `captcha` configuration to `apps/api/src/vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:8]
  captcha: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY
    ? {
        type: "cloudflare_turnstile",
        siteKey: process.env.CLOUDFLARE_TURNSTILE_SITE_KEY,
        secretKey: process.env.CLOUDFLARE_TURNSTILE_SECRET_KEY,
      }
    : undefined,
})
```

Built-in user registration and password recovery routes are protected immediately:

---

### 2. Protect Custom API Routes [#2-protect-custom-api-routes]

Enable captcha verification on any custom Hono endpoint with `withCaptcha: true`:

```ts title="plugins/blog/src/api/modules/comments/routes/create.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route"

export const createCommentRoute = buildRoute({
  pluginId: "blog",
  withCaptcha: true, // [!code ++]
  route: {
    method: "post",
    path: "/",
    responses: { 201: { description: "Comment created" } },
  },
  handler: async (c) => {
    // Execution only reaches here if the captcha token is valid
  },
})
```

---

### 3. Render the Frontend Widget [#3-render-the-frontend-widget]

Include `<Captcha />` in your form and supply the received token to the fetcher:

```tsx title="plugins/blog/src/views/comment-form.tsx"
import { Captcha } from "@vitnode/core/components/captcha"
import { fetcher } from "@vitnode/core/tanstack/fetcher"

export const CommentForm = () => {
  const [captchaToken, setCaptchaToken] = React.useState<string>()

const handleSubmit = async () => {
    await fetcher({
      plugin: "@acme/blog",
      method: "post",
      module: "comments",
      path: "/",
      captchaToken, // [!code ++]
      args: { body: { text: "Nice article!" } },
    })
  }

return (
    <form onSubmit={handleSubmit}>
      <textarea />
      <Captcha onVerify={setCaptchaToken} />
      <button disabled={!captchaToken}>Submit Comment</button>
    </form>
  )
}
```

---

## Supported Providers [#supported-providers]

## Learn More [#learn-more]

# Google reCAPTCHA v3 (/docs/dev/captcha/recaptcha)

reCAPTCHA v3 never asks the visitor to do anything. It watches the page, scores
the request from `0.0` to `1.0`, and VitNode's API accepts anything at `0.5` or
above. Nothing to install - the provider lives in core - so the whole job is two
keys and one config block.

## Quick start [#quick-start]

If you already have a v3 site key and secret key, this is the entire
integration.

```bash title=".env"
RECAPTCHA_SITE_KEY=6Lc...
RECAPTCHA_SECRET_KEY=6Lc...
```

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:5]
  captcha: {
    type: 'recaptcha_v3',
    siteKey: process.env.RECAPTCHA_SITE_KEY,
    secretKey: process.env.RECAPTCHA_SECRET_KEY,
  },
})
```

Restart the API and `/register` starts minting a token on submit. There is no
widget to look at - a reCAPTCHA badge in the corner of the page is the only
visible change.

```ts title="src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:7]
  captcha: process.env.RECAPTCHA_SECRET_KEY
    ? {
        type: 'recaptcha_v3',
        siteKey: process.env.RECAPTCHA_SITE_KEY,
        secretKey: process.env.RECAPTCHA_SECRET_KEY,
      }
    : undefined,
})
```

</Callout>

<Callout title="reCAPTCHA v2 is not supported" type="error">
  `type` accepts `'cloudflare_turnstile'` and `'recaptcha_v3'`, and nothing
  else. VitNode loads Google's script with `render=<siteKey>` and mints the
  token through `grecaptcha.execute`, which a v2 key cannot do - so a v2 pair in
  this block ends as a `400`, either because no token was minted or because the
  verification came back without a score. Register a **score based (v3)** site,
  or use [Cloudflare Turnstile](/docs/dev/captcha/cloudflare) if you want a
  visible widget.
</Callout>

## Register the site [#register-the-site]

### Open the reCAPTCHA admin console [#open-the-recaptcha-admin-console]

Go to the [reCAPTCHA admin console](https://www.google.com/recaptcha/admin/) and
sign in with the Google account that should own the keys.

</Step>
<Step>

### Start a new registration [#start-a-new-registration]

Press the **+** button in the console's header to register another site.

</Step>
<Step>

### Choose score based (v3) and add your domains [#choose-score-based-v3-and-add-your-domains]

Give the registration a **Label** - internal, so your site's name will do - and
pick **Score based (v3)** as the reCAPTCHA type.

Then list every domain the form is served from. Google allows first-level
subdomains automatically, so `your-domain.com` also covers
`www.your-domain.com`. For local development you have to add `localhost`
explicitly; it is not implied.

{/* Image prompt: The Google reCAPTCHA "Register a new site" form with a Label filled in, the "Score based (v3)" reCAPTCHA type radio selected, and two Domains entries reading your-domain.com and localhost, light theme, 1000x700. */}

</Step>
<Step>

### Copy the site key and the secret key [#copy-the-site-key-and-the-secret-key]

Google shows both on the next screen, and they stay available under the
registration's **Settings** tab.

The **site key** is public - the API publishes it so the browser can load
Google's script. The **secret key** is not: it only ever travels from your API
to Google's `siteverify` endpoint.

{/* Image prompt: The Google reCAPTCHA admin console keys screen showing the "SITE KEY" and "SECRET KEY" values with their copy buttons, values partially redacted, light theme, 1000x500. */}

</Step>
<Step>

### Set the environment variables [#set-the-environment-variables]

These names are not magic - they are whatever you read in your config on the
next step. What matters is that both are server-side variables, because the
secret key must never reach a browser bundle.

```bash title=".env"
RECAPTCHA_SITE_KEY=6Lc... # [!code ++]
RECAPTCHA_SECRET_KEY=6Lc... # [!code ++]
```

</Step>
<Step>

### Register the provider [#register-the-provider]

Add the `captcha` block to your API config with `type: 'recaptcha_v3'`.

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

The config is evaluated when the process boots, so restart the API rather than
waiting for a hot reload to notice.

</Step>
<Step>

### Verify it works [#verify-it-works]

Ask the API what it thinks it has configured. The site key comes back on the
public middleware route:

```bash
curl http://localhost:3000/api/@vitnode/core/middleware
# {"isEmail":false,"sso":[],"captcha":{"siteKey":"6Lc...","type":"recaptcha_v3"}}
```

Then open `/register`. Google's badge appears in the bottom corner of the page,
the **Register** button is enabled as soon as the script loads, and a completed
registration means the score cleared `0.5`.

The AdminCP confirms it from the other side: **AdminCP → System →
Integrations** (`/admin/core/system/integrations`) shows the **Captcha** card as
_Active_, with **reCAPTCHA v3** underneath.

Google's own console is the third view. Under the registration's analytics you
should see the request appear, with the score it was given.

</Step>
</Steps>

## What VitNode sends and checks [#what-vitnode-sends-and-checks]

Useful when the console's numbers and your form's behaviour disagree.

| Thing            | Value                                                                  |
| ---------------- | ---------------------------------------------------------------------- |
| Script           | `https://www.google.com/recaptcha/api.js?hl=<locale>&render=<siteKey>` |
| Token minted by  | `grecaptcha.execute(siteKey, { action: 'submit' })`                    |
| Action name      | `submit` - always, and the API does not verify it                      |
| Verify endpoint  | `https://www.google.com/recaptcha/api/siteverify`                      |
| Accepted when    | `success === true` **and** `score >= 0.5`                              |
| Threshold        | `0.5`, hardcoded in `captchaMiddleware`                                |
| Token travels as | the header `x-vitnode-captcha-token`                                   |

The visitor's IP is forwarded as `remoteip`. It is the address of the socket the
request arrived on, falling back to `127.0.0.1` when the runtime exposes no
connection info. Proxy headers like `x-forwarded-for` are deliberately ignored -
the caller writes them - so behind a reverse proxy this is your proxy's address
and the score reflects your server rather than the person filling the form.

## Gotchas [#gotchas]

<Callout type="warn" title="The 0.5 threshold is not configurable">
  It is a constant in the middleware, not a config option, so you cannot loosen
  it for a site that keeps scoring low or tighten it for one under attack. If
  you need a different number, the honest options are a pull request or
  [Cloudflare Turnstile](/docs/dev/captcha/cloudflare), which has no score in
  the first place.
</Callout>

<Callout type="warn" title="A low score looks exactly like a wrong key">
  Both come back as `400 Captcha validation failed`, because the middleware does
  not pass Google's `error-codes` through to the response. Check the
  registration's analytics in the admin console: a request that arrived with a
  low score is a scoring problem, and no request at all is a key or domain
  problem.
</Callout>

<Callout type="warn" title="A rejected submit leaves the button disabled">
  `AutoForm` calls `onReset()` after every submission, which clears `isReady` -
  and with v3 there is no widget callback to set it back. A form that stays on
  screen after a failure ("email already exists") therefore has a dead submit
  button until it is remounted. Turnstile does not have this problem, because
  `turnstile.reset()` makes the widget call back again.
</Callout>

## Next [#next]

# Build and start for production (/docs/dev/cli/build)

`vitnode build` runs your project's real production build and reports the size of every file it wrote. `vitnode start` then runs the server that build produced, and tells you once it accepts connections.

```bash
vitnode build
vitnode start
```

## Build an app [#build-an-app]

```txt title="vitnode build (shortened)"
◆ VitNode
  Production build

✓ Configuration loaded, plugin routes generated  1.5s
  ✓ Building client  21.7s
  ✓ Building server  12.8s
  ✓ Packaging server (Nitro)  21.9s
  ✓ Measuring output  1.1s

Output

Client JS  .output/public
  File                              Size       gzip
  ─────────────────────────────────────────────────
  ▲ assets/custom-emoji-BPTfd_f5.js   820.6 kB   163.2 kB
  ! assets/editor-CUh_DSIT.js         319.4 kB   101.0 kB
  ✓ assets/search-DxtCMbN7.js         223.9 kB    69.1 kB
  … 4721 more not shown (--verbose lists all) - 4731 files, 18.1 MB, gzip 4.5 MB

Server  .output/server
  File          Size
  ──────────────────
  ✓ index.mjs   1.2 MB

✓ Built in 1m 6s
  Run pnpm start to serve it.
```

The last line names your app's `start` script, run with the package manager you use - `pnpm start`, `bun start`, `yarn start` or `npm start`. An app without a `start` script is told to run `vitnode start` instead.

The steps are the build environments your app really has. For a TanStack Start app with Nitro, that is the client, the server, then Nitro's packaged server. VitNode's Vite plugin generates plugin routes and registries while the configuration loads.

The symbols mark how a file compares with its size budget: `✓` is fine, `!` is worth a look and `▲` is large. From the second build on, you also see what grew or shrank since the last one. [Bundle size report](/docs/dev/cli/bundle-size) explains the thresholds, the comparison and `--analyze`.

### See how each page is served [#see-how-each-page-is-served]

The build ends with every page route your app serves - your own route files and the pages of core and every plugin - with how it is rendered and whether its HTML is reused:

```txt title="vitnode build (end of the output, shortened)"
Routes
  Route                                               Rendering     Page cache
  ────────────────────────────────────────────────────────────────────────────────────────────────────
  /                                                   Static        Build-time HTML
  ├ /                                                 prerendered
  └ /pl                                               prerendered
  /admin/*  24 AdminCP routes (--verbose lists all)   SSR           None
  /blog/:slug                                         SSR           TTL 5m · SWR 1m
  └ /pl/wpisy/:slug                                   pattern
  /login                                              SSR           None
  /solutions/:slug                                    Partial       Build-time HTML × 10, others: None
  ├ /solutions/help-center                            prerendered
  └ … 9 more URLs

Static          HTML written at build time; a route with parameters lists the URLs it generated
  SSR, cached     rendered on request, then reused for every visitor (TTL, then SWR window)
  SSR, uncached   rendered on request for each visitor

Page cache storage: memory - one copy per server process, emptied on restart.
```

- **Rendering** is `Static` when every language has a prerendered file, `Partial` when only some URLs of the route do, and `SSR` otherwise. A route with a parameter, such as `/solutions/:slug`, is partial once any of its values is prerendered. Its row shows the pattern, and the `prerendered` lines under it are the concrete URLs the build wrote, each page followed by its translations.
- **Page cache** shows the [page cache](/docs/dev/cache/pages) policy the server applies after your app's overrides: `TTL 5m · SWR 1m`, or `None`. `(app)` marks a policy set in `vitNodeConfig.pageCache.routes`, and `None (disabled by app)` a plugin policy your app turned off. The `pattern` lines are the same route in your other languages and domains, which the cache keys separately.
- In a color terminal, static output is green, cached SSR is blue and uncached SSR keeps the normal text color.

The last line names the storage when the build can tell it. Redis is reported as runtime-dependent, because the server connects to `REDIS_URL` only when it starts. If routes declare a policy but `src/server.ts` does not use `withPageCache`, the build warns that nothing is cached. The report describes configuration, not how often the cache is hit.

The AdminCP is never prerendered or cached, so its routes share one line unless you pass `--verbose`. Nothing is static until you ask for it: [Prerender static pages](/docs/dev/deployments/prerendering) shows how.

## Build an API app or a plugin [#build-an-api-app-or-a-plugin]

The same command builds other project types:

| Project        | What `vitnode build` does                                                         |
| -------------- | --------------------------------------------------------------------------------- |
| API app (Node) | Compiles with `tsc` and `tsc-alias` into `dist`, then lists the output            |
| API app (Bun)  | Nothing: Bun runs `src/index.ts` directly                                         |
| Plugin package | Compiles `src` into `dist/src` with tsdown and checks types with `tsc --noEmit` |

```txt title="vitnode build in a plugin package"
◆ VitNode
  Building @acme/blog

✓ API registry generated
  ✓ Compiling sources  8.0s
  ✓ Checking types  7.3s

✓ Built in 8.0s
```

Compiling and type checking run at the same time, and both must pass. [Build and watch a plugin](/docs/dev/plugins/build) explains what ends up in `dist`.

## When a build fails [#when-a-build-fails]

```txt
✖ Build failed
  Plugin   @vitnode/blog
  File     plugins/blog/src/pages/post.tsx:42:9
  Step     vite:oxc

Missing export: title
```

`Plugin` appears when the failing file belongs to a VitNode plugin package, and `File` and `Step` when the bundler reported them. Below them you get the bundler's message and a code frame, then the last 60 lines of build output. Run with `--verbose` for the full output and stack trace.

## Start the production server [#start-the-production-server]

```bash
vitnode start
```

```txt
◆ VitNode
  Production

● Running  http://localhost:3000
```

`vitnode start` is not a second server. It runs your build's own entry, exactly as `node <entry>` would, and adds two things: "Running" appears only once the server accepts connections, and <kbd>Ctrl</kbd>+<kbd>C</kbd> gives the server time to close cleanly.

| Project        | Entry it runs                                                     | Default port |
| -------------- | ----------------------------------------------------------------- | ------------ |
| App            | Nitro's server entry, usually `.output/server/index.mjs`, on Node | `3000`       |
| API app (Node) | `dist/index.js` on Node                                           | `8000`       |
| API app (Bun)  | `src/index.ts` on Bun                                             | `8000`       |

`--port` and `--host` set the `PORT` and `HOST` variables your server already reads. The port falls back to `PORT`, then the default above. `NODE_ENV` is set to `production` unless you set it yourself.

`vitnode start` stops with an error when:

- there is no build yet: run `vitnode build` first
- the app was built for a hosting platform, such as the `vercel` Nitro preset, because that platform runs it
- something already listens on the port
- the runtime is missing, for example Bun on a server that only has Node
- the server exits before it is ready, or does not listen within 60 seconds

## Next steps [#next-steps]

# Bundle size report (/docs/dev/cli/bundle-size)

After an app build, `vitnode build` reports every file it wrote, warns about oversized client bundles and compares the result with your previous build. This page explains each part of that report. To run a build, see [Build and start for production](/docs/dev/cli/build).

The report prints in this order: **Output**, **Bundle changes**, **Bundle analysis** (with `--analyze`) and **Warnings**.

## Output [#output]

Files are grouped as client JavaScript, CSS, assets, server files and other files. Each group shows its largest files: 10 for client JavaScript, 5 for the rest. Run with `--verbose` to list every file.

| Column | Meaning                                                                     |
| ------ | --------------------------------------------------------------------------- |
| Size   | The file on disk, after minification                                        |
| gzip   | What a browser downloads with gzip, for client JavaScript and CSS only      |
| brotli | Brotli at quality 11, with `--analyze`, for the 25 largest JS and CSS files |

Sizes use decimal units (`1 kB` = 1000 bytes), like Vite and browser dev tools. Server files are never compressed, because nobody downloads them.

## Size thresholds [#size-thresholds]

Every file gets a symbol from its type and size. Client JavaScript has the strictest budget, because every visitor downloads, parses and runs it. A server bundle is read once at boot, so its limits are much looser.

| File type     | `✓` good | `✓` normal | `!` warning | `▲` large |
| ------------- | -------- | ---------- | ----------- | --------- |
| Client JS     | ≤ 100 kB | ≤ 250 kB   | ≤ 500 kB    | > 500 kB  |
| CSS           | ≤ 50 kB  | ≤ 100 kB   | ≤ 250 kB    | > 250 kB  |
| Assets, other | ≤ 100 kB | ≤ 500 kB   | ≤ 1 MB      | > 1 MB    |
| Server        | ≤ 1 MB   | ≤ 5 MB     | ≤ 20 MB     | > 20 MB   |

The 500 kB line for client JavaScript matches Vite's own chunk size warning.

## Warnings [#warnings]

Client chunks get a warning from 250 kB. CSS and assets get one only when they are large. Server files never do. Each warning says what to try:

```txt
Warnings
▲ admin-D2kL8aQ1.js is larger than the recommended 500.0 kB for a client chunk.
    assets/admin-D2kL8aQ1.js  612.4 kB
  Consider:
  • @tiptap/core makes up 41.2% of admin-D2kL8aQ1.js - import it with import() where it is needed
  • load heavy libraries with dynamic import() where they are used
  • give pages their own chunk: component: lazy(() => import(...)) in routes.ts
  • lazy-load heavy UI such as editors and dialogs with React.lazy + Suspense
```

<Callout type="info" title="Warnings never fail a build">
  Size warnings are recommendations. A build fails only when the build itself
  fails.
</Callout>

## Bundle changes [#bundle-changes]

From the second build on, the report shows how client JavaScript, CSS and assets changed:

```txt
Bundle changes
  File                         Size       Change
  ──────────────────────────────────────────────────────
  assets/editor-H2kq9ZZ1.js    428.6 kB   +86.1 kB   +25.1%   ▲
  assets/admin-Dk2L8aQ1.js     612.4 kB   -12.8 kB    -2.0%
  assets/new-page-Ab12cdEf.js    4.1 kB    +4.1 kB            new
  Client JS total 18.1 MB (+77.4 kB)
```

- `▲` marks a file that grew by more than 10% and by more than 10 kB.
- Files that changed by less than 1 kB are left out. New and removed files are always listed.
- The 10 biggest changes are shown; `--verbose` shows all of them.

Files are matched by what they contain, not by name, so a new content hash does not break the comparison:

- an entry chunk is matched by the module it is built from, such as `src/pages/editor.tsx`
- a shared chunk is matched by its name and the module that makes up most of it
- an asset is matched by its source file

A shared chunk with no entry module can show up as one file removed and one added when a refactor changes which module makes up most of it.

The previous sizes are stored in `node_modules/.cache/vitnode/build-snapshot.json`, never in your repository. A missing or unreadable snapshot only skips the comparison.

## Analyze a bundle [#analyze-a-bundle]

```bash
vitnode build --analyze
```

```txt
Bundle analysis

assets/custom-emoji-BPTfd_f5.js  820.6 kB
    @tiptap/extension-emoji     ≈ 422.3 kB    51.5%
    @tiptap/core                ≈ 120.7 kB    14.7%
    prosemirror-view            ≈ 117.9 kB    14.4%
    application code             ≈ 50.8 kB     6.2%
    other                        ≈ 57.9 kB     7.1%
```

`--analyze` breaks the five largest client chunks down by package, showing up to six contributors each. It uses the module sizes the bundler records, measured before minification. The percentages are exact, and each size (`≈`) is that share of the file on disk. Workspace packages show by name, and your app's own files show as `application code`.

A package that makes up at least 30% of a chunk is also named in that chunk's warning. The analysis prints in the terminal; nothing opens in a browser.

## Next steps [#next-steps]

# Use the CLI in CI (/docs/dev/cli/ci)

The VitNode CLI runs in pipelines without changes: it never waits for input there, and every command exits with a non-zero code when it fails, so a pipeline stops at the first problem.

```bash
vitnode plugin validate
vitnode build --plain
vitnode db migrate --yes
```

Run each command in your app's folder, so the CLI finds the app's config.

## GitHub Actions [#github-actions]

```yaml title=".github/workflows/build.yml"
name: Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v5
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build:plugins
      - run: pnpm --filter web exec vitnode plugin validate
      - run: pnpm --filter web exec vitnode build --plain
```

`--filter web` runs `vitnode` in the `web` app's folder. Plugins are built first, because validation and the app build both read their `dist` output.

To compare bundle sizes between runs, cache `node_modules/.cache/vitnode`. That is where `vitnode build` keeps the previous build's sizes.

## Migrate during deployment [#migrate-during-deployment]

```bash
POSTGRES_URL=postgresql://... vitnode db migrate --yes
vitnode start
```

Run migrations once per deployment, before the new version starts. `--yes` is required, because the CLI never waits for an answer without an interactive terminal. If two instances start at once, the second waits for the first instead of racing it.

## What changes in a pipeline [#what-changes-in-a-pipeline]

Under CI, with piped output, or when stdin is not a terminal, the CLI:

- shows no spinners, animations or cursor movement
- never prompts: a command that needs a confirmation exits with code `2` and names the flag to pass, such as `--yes`

`--plain` gives stable, prefixed lines that are easy to grep:

```txt title="vitnode build --plain (excerpt)"
VitNode - Production build
[OK] Configuration loaded, plugin routes generated (1.5s)
[OK] Building client (21.7s)
[OK] Building server (12.8s)
[WARN] admin-D2kL8aQ1.js is larger than the recommended 500.0 kB for a client chunk.
```

Size warnings never fail a build. [Output and exit codes](/docs/dev/cli/output) lists every exit code and how colors are chosen.

## Next steps [#next-steps]

# Database commands (/docs/dev/cli/database)

The `vitnode db` commands manage your database schema through migrations: files that describe each change, which you commit so every database gets the same changes in the same order.

```bash
vitnode db generate   # write a migration for your schema changes
vitnode db migrate    # apply pending migrations and seed initial data
vitnode db status     # check the connection and what is pending
vitnode db push       # sync the schema directly, development only
```

Run them in the app that owns the database, the one with `drizzle.config.ts`. They use your app's own Drizzle configuration, connection and migration table.

## Generate, migrate or push? [#generate-migrate-or-push]

| Command       | What it changes               | Use it                                   |
| ------------- | ----------------------------- | ---------------------------------------- |
| `db generate` | Writes a migration file       | After changing tables, before committing |
| `db migrate`  | Applies migration files       | Everywhere: development, CI, production  |
| `db push`     | Changes the database directly | Quick experiments in development         |

## Generate a migration [#generate-a-migration]

```bash
vitnode db generate --name notifications
```

```txt
◆ VitNode
  Database

✓ Checking migration history  2.7s
  ✓ Comparing schema with the last migration  3.1s

Schema changes detected
  + table notifications
  + table notification_preferences
  + column users.notification_count

✓ Generating migration  3.1s

✓ 20261005233216_notifications
  Apply it with vitnode db migrate.
```

The list comes from drizzle-kit's own plan, so it is exactly what the migration contains. With no changes, the command prints `No schema changes - nothing to generate.` and exits with `0`.

When drizzle-kit cannot tell whether a column was renamed or replaced, the command lists those changes and hands the terminal to drizzle-kit so you can answer. Without an interactive terminal it stops with exit code `2` instead of guessing.

<Callout type="info" title="Build plugins first">
  Migrations are generated from each plugin's build output. After changing a
  plugin's tables, run `vitnode build` in the plugin, then `vitnode db
  generate`.
</Callout>

## Apply migrations [#apply-migrations]

```bash
vitnode db migrate
```

```txt
◆ VitNode
  Database migration

✓ Connecting to the database  26ms

Pending migrations
  ○ 20261004081732_add_core_notifications
  ○ 20261004112416_allow_null_notification_digest_schedule

◇ Apply 2 migrations? Yes
  ✓ Applying migrations  840ms
  ✓ 20261004081732_add_core_notifications
  ✓ 20261004112416_allow_null_notification_digest_schedule

✓ Database is up to date.
```

`db migrate` applies all pending migrations in one transaction, so a failed migration leaves nothing half-applied, and the error shows Postgres' own details. It then seeds the data every VitNode installation needs, such as languages, roles and permissions.

The seed also runs when no migration is pending. That way a language you add to your config gets its row without a new migration, and `db migrate` stays safe to run on every deployment.

If another process is already preparing the same database, for example a second container starting at the same time, `db migrate` waits for it to finish instead of racing it.

Without an interactive terminal, confirm with `--yes`:

```bash
vitnode db migrate --yes
```

Without `--yes`, a non-interactive run with pending migrations exits with code `2` instead of waiting for an answer.

## Check the status [#check-the-status]

```bash
vitnode db status
```

```txt
◆ VitNode
  Database

Provider   PostgreSQL
  Database   vitnode @ localhost:5432
  Status     ● connected

Migrations
  Applied   64
  Pending   1

Pending
  ○ 20261005233216_notifications
```

`db status` only reads. It always connects, so the status is never guessed from the config alone. It warns about an applied migration whose file changed since it ran, or whose file is missing. When the database does not answer within 10 seconds, it exits with code `1`.

## Push the schema in development [#push-the-schema-in-development]

```bash
vitnode db push
```

```txt
◆ VitNode
  Push database schema

! Direct schema synchronization is intended for development.

Changes
  - table zz_drafts
  + index notifications.notifications_user_id_idx

Data loss
  ! table zz_drafts (non empty)

◇ Apply 2 changes, including 1 that deletes data? No
```

`db push` changes the database without writing a migration. It shows every change first and names each one that deletes data. The data-loss question defaults to No.

From a script, pass `--yes` to apply and `--accept-data-loss` to allow changes that delete data. Without `--accept-data-loss`, a non-interactive run that would delete data exits with code `2`.

<Callout type="warn" title="db push refuses production">
  When `NODE_ENV` is `production`, `vitnode db push` stops before connecting and
  exits with code `2`. Use `db generate` and `db migrate` instead. Pass
  `--force` only if you really mean to push to that database.
</Callout>

## Options [#options]

| Command       | Option               | Effect                                        |
| ------------- | -------------------- | --------------------------------------------- |
| `db generate` | `--name <name>`      | Name the migration folder                     |
| `db migrate`  | `-y, --yes`          | Apply without asking                          |
| `db push`     | `-y, --yes`          | Apply without asking                          |
| `db push`     | `--accept-data-loss` | Allow changes that delete data                |
| `db push`     | `--force`            | Allow pushing when `NODE_ENV` is `production` |

Every command also accepts `--plain` and `--verbose`. With `--verbose`, the change lists are not shortened and a failure shows the complete drizzle-kit output.

## Next steps [#next-steps]

# Run in development (/docs/dev/cli/dev)

`vitnode dev` starts whatever the current folder is: an app gets a Vite dev server, an API app gets a watching Node or Bun process, and a plugin package gets tsdown and the type checker in watch mode. Run it from the project's folder.

```bash
vitnode dev
```

## Start an app [#start-an-app]

```txt
◆ VitNode
  Development

✓ Loading configuration  31ms
  ✓ Checking database schema  1.2s
  ✓ Database connected  up to date
  ✓ 2 plugins loaded
  ✓ Starting dev server  2.6s

Web       http://localhost:3000
  AdminCP   http://localhost:3000/admin
  API       http://localhost:3000/api
────────────────────────────────────────
GET   /                                   200   180ms
GET   /api/@vitnode/core/users/session    200     6ms
HMR   src/routes/_main/index.tsx
```

Below the line, the CLI logs page loads, API calls, server functions and every non-GET request, plus each hot update (`HMR`). Requests for scripts, styles and images are left out so the log stays readable.

The URLs are the ones Vite actually bound. The `API` row appears when the app also serves the API.

### Choose the port and host [#choose-the-port-and-host]

The port is the first one set of: `--port`, the `PORT` variable, `server.port` in `vite.config.ts`, then `3000`.

```bash
vitnode dev --port 4000
vitnode dev --host              # listen on every address
vitnode dev --host 127.0.0.1    # listen on one address
```

With `--host`, a `Network` row shows the address other devices on your network can open, which is handy for testing on a phone.

### Keyboard shortcuts [#keyboard-shortcuts]

In an interactive terminal, type a key and press <kbd>Enter</kbd>:

| Key | Action        |
| --- | ------------- |
| `o` | Open the site |
| `a` | Open AdminCP  |
| `r` | Restart       |
| `q` | Quit          |

<kbd>Ctrl</kbd>+<kbd>C</kbd> closes the dev server and every watcher it started.

## Database setup before the server starts [#database-setup-before-the-server-starts]

When the app owns the database (it has both a `drizzle.config.ts` and `src/vitnode.api.config.ts`), `vitnode dev` prepares the database before anything serves a request:

1. It compares your schema with the last migration and generates a migration when they differ.
2. It applies pending migrations.
3. It seeds the data every installation needs: languages, roles and permissions.

The server starts only after this finishes, so your first page load never hits a half-built schema. When the terminal is not interactive and drizzle-kit needs to ask whether a column was renamed, the CLI skips generation with a warning. Run `vitnode db generate` yourself to answer it. See [Database commands](/docs/dev/cli/database).

## Start an API app [#start-an-api-app]

In a folder with `src/vitnode.api.config.ts` and no Vite config, `vitnode dev` runs your API with a file watcher:

```txt
  API       http://localhost:8000/api
  Runtime   Node (tsx watch)
```

The port is `--port`, then `PORT`, then `8000`. The CLI passes it to your API as `PORT`. `--host` is passed as `HOST`, and a bare `--host` means `0.0.0.0`. Generated API apps read both variables.

The API runs on Bun, with `bun --hot`, when any of these is true:

- you started the script with Bun (`bun run dev`)
- the nearest `packageManager` field says `bun@...`
- the nearest lockfile is `bun.lock` or `bun.lockb`

Otherwise it runs on Node with `tsx watch`.

## Develop a plugin package [#develop-a-plugin-package]

In a plugin package, `vitnode dev` regenerates the plugin's API registry, then watches `src` with tsdown and runs `tsc` in watch mode to report type errors. Apps that use the plugin import its `dist` folder, so they reload as you save.

```txt
◆ VitNode
  Plugin development - @acme/blog

✓ API registry generated
  ● Watching sources - apps using this plugin reload as dist/ changes

tsdown js    Rebuilt in 71ms.
tsdown types Rebuilt in 4493ms.
```

The JavaScript (`tsdown js`) is rebuilt within milliseconds of a save. Declarations (`tsdown types`) follow once TypeScript catches up, so your editor sees new types a few seconds later. A syntax error is printed and the next save rebuilds. If a watcher fails to start, for example because tsdown is not installed, the CLI stops the others and exits with code `1`.

[Build and watch a plugin](/docs/dev/plugins/build) covers added and deleted files, assets and what your app sees while a rebuild is written.

## Next steps [#next-steps]

# VitNode CLI (/docs/dev/cli)

`vitnode` is the command-line tool for VitNode projects. It ships with `@vitnode/core`, so every VitNode app and plugin already has it. You do not install anything extra.

```bash tab="bun"
bun run vitnode dev
```

```bash tab="pnpm"
pnpm vitnode dev
```

```bash tab="npm"
npx vitnode dev
```

</Tabs>

Generated projects already call it from their `package.json` scripts, so `pnpm dev` and `pnpm start` run `vitnode dev` and `vitnode start` for you.

## Commands [#commands]

| Command                   | What it does                                   | Guide                                   |
| ------------------------- | ---------------------------------------------- | --------------------------------------- |
| `vitnode dev`             | Start the development environment              | [Run in development](/docs/dev/cli/dev) |
| `vitnode build`           | Build for production and report bundle sizes   | [Build and start](/docs/dev/cli/build)  |
| `vitnode start`           | Start the production server                    | [Build and start](/docs/dev/cli/build)  |
| `vitnode plugin list`     | List the plugins your app uses                 | [Plugins](/docs/dev/cli/plugins)        |
| `vitnode plugin validate` | Check plugins the way your app will load them  | [Plugins](/docs/dev/cli/plugins)        |
| `vitnode db generate`     | Write a migration for schema changes           | [Database](/docs/dev/cli/database)      |
| `vitnode db migrate`      | Apply pending migrations and seed initial data | [Database](/docs/dev/cli/database)      |
| `vitnode db status`       | Show the connection and what is pending        | [Database](/docs/dev/cli/database)      |
| `vitnode db push`         | Sync the schema directly, in development only  | [Database](/docs/dev/cli/database)      |
| `vitnode i18n <command>`  | Add, check, sync and translate languages       | [Internationalization](/docs/dev/i18n)  |

To create a plugin, use the project generator: `create-vitnode-app --plugin`. See [Create a plugin](/docs/dev/plugins/create).

Run `vitnode` alone (or `vitnode --help`) for a short overview, `vitnode <command> --help` for a command's options, and `vitnode --version` for the installed `@vitnode/core` version.

## How the CLI picks your project [#how-the-cli-picks-your-project]

`dev`, `build` and `start` act on the project in the current folder. The CLI walks up to the nearest `package.json` and checks, in this order:

| The folder has                                                         | It is a        |
| ---------------------------------------------------------------------- | -------------- |
| `vite.config.ts` (or `.mts`, `.js`...)                                 | App            |
| `src/vitnode.api.config.ts`                                            | API app        |
| `tsconfig.build.json` and `package.json` `exports` into `./dist/src/` | Plugin package |

Run it at a monorepo root and the CLI stops with a hint to `cd` into your app, such as `apps/web`, instead of guessing which project you meant.

## Works with your tools, not instead of them [#works-with-your-tools-not-instead-of-them]

The CLI drives the tools your project already uses: Vite through its JavaScript API, TanStack Start through your `vite.config.ts`, and your project's own `drizzle-kit`. You can still run `vite` or `drizzle-kit` directly. `vitnode` adds the database bootstrap, plugin checks and readable output around them.

## Next steps [#next-steps]

# Output and exit codes (/docs/dev/cli/output)

Every `vitnode` command accepts the same output options and uses the same exit codes. Use this page to tune the output for logs or debugging, or to react to a failure in a script.

## Output options [#output-options]

| Option          | Effect                                                                                                                                       |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--plain`       | Line-based output without colors, symbols or animation. Status lines start with `[OK]`, `[WARN]`, `[FAIL]`, `[ERROR]`, `[INFO]` or `[SKIP]`. |
| `--verbose`     | Show the underlying tool output (Vite, compilers), every file and change, and full stack traces                                              |
| `-h, --help`    | Show the command and its options                                                                                                             |
| `-v, --version` | Print the installed `@vitnode/core` version                                                                                                  |

Setting `VITNODE_DEBUG=1` turns on `--verbose` for every command.

Without `--verbose`, messages that Vite and its plugins print during a build are held back, so they do not break the progress lines. The CLI tells you how many it hid, and prints the last 60 lines of captured output if the command fails.

## Interactive and non-interactive terminals [#interactive-and-non-interactive-terminals]

The CLI treats a terminal as interactive when stdin and stdout are both terminals, `TERM` is not `dumb`, `--plain` is not set, and no CI variable is set. It checks `CI`, `CONTINUOUS_INTEGRATION`, `BUILD_NUMBER`, `RUN_ID`, `GITHUB_ACTIONS`, `GITLAB_CI`, `BUILDKITE` and `TF_BUILD`. A value of `0` or `false` counts as unset.

In a non-interactive terminal, the CLI never shows spinners or prompts. A command that needs an answer exits with code `2` instead of waiting. For a confirmation, the error names the flag that answers it, such as `--yes`.

## Colors [#colors]

Colors are on when stdout is a terminal and `TERM` is not `dumb`.

- `NO_COLOR` with any non-empty value turns colors off.
- `FORCE_COLOR` turns them on even in piped output, unless its value is `0` or `false`.
- `--plain` turns them off whatever the variables say.

On a Linux console (`TERM=linux`) and older Windows consoles, the CLI uses plain ASCII symbols instead of `✓` and `▲`.

## Exit codes [#exit-codes]

| Code  | Meaning                                                                                    |
| ----- | ------------------------------------------------------------------------------------------ |
| `0`   | Success, including a confirmation you declined                                             |
| `1`   | The command failed: a build error, invalid plugin, migration error or unreachable database |
| `2`   | The command needs a change from you: see below                                             |
| `130` | Cancelled with <kbd>Ctrl</kbd>+<kbd>C</kbd> at a prompt                                    |

Exit code `2` means nothing ran because the input was not usable as given:

- an unknown command or option (the CLI suggests the closest match)
- an invalid value, such as a port outside 1-65535 or an unknown plugin name
- a missing `--yes` or `--accept-data-loss` in a non-interactive terminal
- a drizzle-kit rename question in a non-interactive terminal
- `vitnode db push` with `NODE_ENV=production` and no `--force`

<kbd>Ctrl</kbd>+<kbd>C</kbd> while `vitnode dev` or `vitnode start` is running
stops the server cleanly and exits with `0`.

## Related [#related]

- [Use the CLI in CI](/docs/dev/cli/ci)
- [VitNode CLI](/docs/dev/cli)

# List and validate plugins (/docs/dev/cli/plugins)

`vitnode plugin list` shows which plugins your app uses and where they come from. `vitnode plugin validate` loads each plugin the way your app will, so a broken plugin fails here with a clear message instead of halfway through a build.

To create a plugin, use the generator, which also registers, installs and builds it. See [Create a plugin](/docs/dev/plugins/create).

## List plugins [#list-plugins]

Run it from your app, or from anywhere in its workspace:

```bash
vitnode plugin list
```

```txt
◆ VitNode
  Plugins

Plugin                         Version           Source
  ───────────────────────────────────────────────────────────
  @vitnode/blog                  2.0.0-canary.13   workspace
  @acme/search                   1.1.2             package
  @acme/forum (not configured)   0.1.0             workspace

2 plugins configured in this app
```

The list comes from your app's `vitnode.config.ts`, read by the same loader the app's build uses.

| Value              | Meaning                                                       |
| ------------------ | ------------------------------------------------------------- |
| `workspace`        | A package in this repository                                  |
| `package`          | Installed from a registry into `node_modules`                 |
| `(not configured)` | A workspace plugin your app does not use yet                  |
| `not installed`    | The app's config names the plugin, but the package is missing |

`--verbose` adds each plugin's path and description.

## Validate plugins [#validate-plugins]

```bash
vitnode plugin validate        # every plugin, or the one you are in
vitnode plugin validate blog   # one plugin, by id, package name or folder
```

```txt
◆ VitNode
  Validate plugins

@vitnode/blog  plugins/blog
  ✓ Package  2.0.0-canary.13
  ✓ Plugin definition
  ✓ API definition
  ✓ Routes  3 routes
  ✓ Translations  en
  ✓ AdminCP navigation
  ✓ Database schema  6 tables

✓ 1 plugin valid
```

Validation reads the plugin's build output, the `dist` files your app imports, so build the plugin first. Each check runs only when the plugin has that part:

| Check              | Fails when                                                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Package            | `package.json` is missing, `name` is not a valid plugin id, `type` is not `module`, or `exports` lacks `./*` or `./config` |
| Build output       | `dist/src/config.js` is missing: build the plugin first                                                                    |
| Plugin definition  | `dist/src/config.js` exports no `buildPlugin()` factory, or its `pluginId` is not the package name                         |
| API definition     | `dist/src/config.api.js` exports no working `buildApiPlugin()` factory, or its `pluginId` does not match                   |
| Routes             | The route tree does not compile, or a `lazy(() => import(...))` page file is missing                                       |
| Translations       | A locale file is unreadable, lacks the plugin's top-level key, or a route's `messages` namespace is missing                |
| AdminCP navigation | A nav item requires a permission the plugin does not register in `permissionStaff.admin`                                   |
| Database schema    | A schema module fails to load, or two modules declare the same table                                                       |

A translation file that is only missing some keys gets a `!` warning, not a failure, so a half-translated language does not block a release.

A failure says what is wrong and where:

```txt
  ✖ AdminCP navigation
      AdminCP navigation item /admin/blog requires the permission posts.can_manage,
      but @acme/blog does not register it in buildApiPlugin({ permissionStaff: { admin } }).
      dist/src/admin/nav.js

✖ 1 plugin failed validation: @acme/blog
```

`vitnode plugin validate` exits with code `1` when any plugin is invalid, so it can gate a CI job. An unknown plugin name exits with code `2` and lists the plugins it knows.

## Next steps [#next-steps]

# Configuration (/docs/dev/configuration)

A VitNode app has two configuration files, and the line between them is one
question: **may a browser hold this?**

---

## `vitnode.config.ts` - the shared config [#vitnodeconfigts---the-shared-config]

```ts title="apps/web/src/vitnode.config.ts"
import { blogPlugin } from '@vitnode/blog/config'
import { LogoVitNodeBrand } from '@vitnode/core/components/logo-vitnode'
import { buildConfig } from '@vitnode/core/vitnode.config'

export const vitNodeConfig = buildConfig({
  debug: false,
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'pl', name: 'Polski' },
    ],
    timeZone: 'UTC',
  },
  logo: LogoVitNodeBrand,
  metadata: {
    shortTitle: 'VitNode',
    title: 'VitNode',
  },
  plugins: [blogPlugin()],
  theme: {
    defaultTheme: 'system',
  },
})
```

Three very different readers depend on this file:

1. **The document shell** renders `metadata`, `logo`, `theme` and `debug` - in the
   browser as well as on the server.
2. **The locale runtime** derives routing from `i18n`.
3. **Your Vite build** loads it with `jiti` while Vite is still resolving its
   own config, to find out which plugins to generate route, navigation and
   content-registry imports for.

<Callout type="warn" title="Plain data only">
  Because of reader 3, this file is executed at build time; because of reader 1
  it is bundled for a browser. So it holds plain data and plugin *identity* -
  never a `() => import(...)` message loader, and never a module that reaches a
  database. The one exception is `logo`: a small, self-contained component.
</Callout>

`buildConfig` keeps `locales` a tuple of literal types, so a `Locale` derived
from it is `'en' | 'pl'` rather than `string`, and `defaultLocale` is checked
against the list right beside it:

```ts title="apps/web/src/vitnode.config.ts"
export type Locale = (typeof vitNodeConfig.i18n.locales)[number]['code']
```

### Logo [#logo]

`logo` is the component the site header shows in its home link. Leave it out
and you get the VitNode logo - which is lovely, but it is probably not your
brand.

```tsx title="src/components/logo.tsx"
export const Logo = () => (
  <img
    alt="Acme"
    className="h-8 w-auto"
    height={32}
    src="/logo.svg"
    width={96}
  />
)
```

```ts title="src/vitnode.config.ts"
import { Logo } from '@/components/logo'

export const vitNodeConfig = buildConfig({
  // ...
  logo: Logo,
})
```

Pass the component itself, not `<Logo />`. Keep it lean: your Vite build
executes this file too, so a logo that imports half your UI makes every
regeneration pass slower.

### View transitions [#view-transitions]

Navigations crossfade and the logo morphs between layouts by default. Set
`viewTransitions` to `false` to swap pages instantly instead:

```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  // ...
  viewTransitions: false,
})
```

See [View transitions](/docs/ui/view-transitions) for what this changes.

### Enabled plugins [#enabled-plugins]

```ts
import { blogPlugin } from '@vitnode/blog/config'

plugins: [blogPlugin()]
```

The factory carries the plugin's identity, its locale barrel and its route
declarations - plain data, and nothing that renders. Its AdminCP navigation and
its Content Engine screens live in the plugin's `admin/nav` and `admin/content`
modules instead, and they never pass through this object.

What a TanStack Start app **renders** comes back through generated projections
of those modules, and that is the part worth knowing:

One literal import per configured plugin, written at build time. So a content
type's editing screen - a Tiptap field, a form layout, a table cell - arrives
with the route that renders it, not with the config that the document shell
imports. Spreading `admin/content` into the factory undoes exactly that: the
whole editing stack rides along with every public page. See
[Plugin routes](/docs/dev/routing) and
[Plugin frontend modules](/docs/content-engine/plugin-files).

<Callout type="info" title="Where its locale files come from">
  The `messages` a factory carries is the plugin's own locale barrel, which loads
  its JSON with `import('./en.json', { with: { type: 'json' } })` - a specifier
  no bundler follows. The factory's `localeFiles` is the same list spelled as
  package subpaths, and that is what your app's translations are loaded from:
  your build writes the loaders into `src/package-messages.gen.ts` for you.
  [Languages & Localization](/docs/dev/i18n) has the detail.
</Callout>

<Callout type="warn" title="Build-time cost">
  Your Vite build executes this file with `jiti` on every regeneration pass to
  discover the plugin list. Running a plugin's registration graph in Node
  measures ~340ms per pass against ~6ms for `buildPlugin({pluginId})`, which is
  the minimum a TanStack host needs - worth knowing if a large plugin set makes
  the dev watcher feel slow.
</Callout>

---

## `vitnode.server.config.ts` - the server-only companion [#vitnodeserverconfigts---the-server-only-companion]

Message loaders read JSON out of a package's build output, which is exactly what
the shared config cannot carry. They go here instead:

```ts title="apps/web/src/vitnode.server.config.ts"
import '@tanstack/react-start/server-only'
import { buildServerConfig } from '@vitnode/core/vitnode.config'

import { appMessages } from '@/locales/app'
import { packageMessages } from '@/package-messages.gen'
import { vitNodeConfig } from '@/vitnode.config'

export const vitNodeServerConfig = buildServerConfig({
  config: vitNodeConfig,
  messages: appMessages,
  packageMessages,
})
```

It **holds** the shared config rather than repeating any of it, so the locale
list your message loaders are resolved against is the same object the router and
the document shell read. Hand the whole thing to the loader:

```ts title="apps/web/src/server/messages.server.ts"
export const loadIntlMessages = createIntlMessagesLoader(vitNodeServerConfig)
```

`packageMessages` is generated from the plugins you configured, and `messages` is
where you reword a string a package translates differently to how you want it.
[Languages & Localization](/docs/dev/i18n) covers both.

<Callout type="info" title="The API has its own config">
  `src/vitnode.api.config.ts` configures the Hono app at `/api/*` - the
  database, storage, email, Redis. In a single app it reads `vitNodeConfig.i18n`
  so the site and its emails agree on which languages exist. In a split
  deployment the API is a separate package and declares its own list - and its
  own `localePrefix`, `domains` and `routePaths`, which must mirror the web
  app's so the content URLs it builds match. See [Localized
  URLs](/docs/dev/i18n/localized-urls).
</Callout>

---

## `start.ts` - the request pipeline [#startts---the-request-pipeline]

TanStack Start expects a `src/start.ts`. In a VitNode app it is one call:

```ts title="apps/web/src/start.ts"
import { createVitNodeStart } from '@vitnode/core/tanstack/start'

import { vitNodeConfig } from '@/vitnode.config'

export const startInstance = createVitNodeStart({ config: vitNodeConfig })
```

`createVitNodeStart` installs three things, and none of them is optional:

| Middleware    | What it does                                                                               |
| :------------ | :----------------------------------------------------------------------------------------- |
| **CSRF**      | Rejects cross-site requests to server functions (`handlerType === 'serverFn'`)             |
| **Locale**    | Canonical `308` redirects, the remembered-locale cookie, and the document cache directive  |
| **Documents** | Forces `Cache-Control: private, no-store` and adds security headers to every HTML response |

<Callout type="warn" title="Why the factory exists">
  Start installs its own CSRF middleware *only* while an app declares no
  `requestMiddleware` at all. The moment an app writes its own list, that
  default is replaced by whatever the list holds - so an app that hand-rolls the
  pipeline and forgets CSRF exposes every server function as an unauthenticated
  cross-site endpoint, silently. Core owns the list so you cannot.
</Callout>

### Why documents are never shared-cacheable [#why-documents-are-never-shared-cacheable]

Every page VitNode renders streams a dehydrated TanStack Query cache into its
HTML, and that cache always holds the visitor's own session - inside `/admin`,
an administrator's entire permission set. So the directive is **forced**, not
defaulted: a route that sets `public, max-age=60` is overwritten rather than
obeyed, because the route is not in a position to know what is in the body it
would be publishing.

Only `text/html` responses are touched. Everything else keeps what it had.

<Callout type="info" title="API caching stays the API's">
  `/api/*` is served by the Hono bridge through this same middleware and passes
  through untouched: no locale redirect, no rewrite, and no cache directive on
  the JSON it answers with. The API decides its own policy with `c.get("cache")`
  - see [Caching](/docs/dev/cache). The one exception proves the rule rather
  than bending it: Swagger UI at `/api/swagger` is HTML, so it gets the document
  directive like any other page an operator reads.
</Callout>

### Security headers on every page [#security-headers-on-every-page]

Every HTML response also gets a small, conservative set of security headers:

There is no script policy and no HSTS by default - a strict script CSP breaks
plugins in creative ways, and HSTS is a promise you should only make once your
domain is HTTPS for good. A header a route sets for itself always wins. To add,
change or drop one install-wide, pass `securityHeaders` (`false` removes a
default):

```ts title="apps/web/src/start.ts"
export const startInstance = createVitNodeStart({
  config: vitNodeConfig,
  // [!code ++:4]
  securityHeaders: {
    'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
    'Referrer-Policy': 'no-referrer',
  },
})
```

### Adding your own middleware [#adding-your-own-middleware]

For things your installation genuinely owns - a request id, a tracing span, a
maintenance-mode gate:

```ts title="apps/web/src/start.ts"
import { createMiddleware } from '@tanstack/react-start'
import { createVitNodeStart } from '@vitnode/core/tanstack/start'

import { vitNodeConfig } from '@/vitnode.config'

const requestId = createMiddleware().server(async ({ next }) => {
  const result = await next()
  result.response.headers.set('x-request-id', crypto.randomUUID())

return result
})

export const startInstance = createVitNodeStart({
  config: vitNodeConfig,
  requestMiddleware: [requestId],
})
```

**Ordering is guaranteed:** CSRF first, then locale handling, then your list in
the order you declared it. You cannot get in front of either. That is not
tidiness - a locale redirect _ends_ the request, so middleware running before it
would run twice for every visitor who arrives at a non-canonical URL, once for
the redirect and once for the page.

---

## `vite.config.ts` [#viteconfigts]

One VitNode plugin, which is the environment handling, the dev server's
dependency pre-bundling, the SSR externals, the Tailwind source list and the
plugin route generator in the order they have to run:

```ts title="apps/web/vite.config.ts"
import { vitnode } from '@vitnode/core/framework/vite'

export default defineConfig({
  plugins: [
    vitnode({ appRoot: import.meta.dirname }),
    nitro({ compressPublicAssets: { brotli: true, gzip: true } }),
    tailwindcss(),
    tanstackStart(),
    viteReact(),
  ],
})
```

`compressPublicAssets` writes a `.br` and a `.gz` twin next to every built asset,
so the Node server from `pnpm start` serves scripts and styles compressed the
way a CDN would. The server-rendered HTML itself is not compressed by the Node
server; put a reverse proxy or a platform such as Vercel in front of it for that.

`appRoot` has to be `import.meta.dirname`: a Vite config is loaded with the
working directory set to wherever the command ran, which in a monorepo is
regularly the repository root.

Publish an extra key to the browser with `clientEnv`:

```ts
vitnode({ appRoot: import.meta.dirname, clientEnv: ['VITNODE_MAP_KEY'] })
```

Everything named there is compiled into JavaScript anyone can read, so add a key
only when something in the browser genuinely reads it. The five plugins are
still exported individually - `vitNodeEnv`, `vitNodeOptimizeDeps`,
`vitNodeSsrExternals`, `vitNodeTailwindSources`, `vitNodePluginRoutes` - if you
ever need to drop or reorder one.

### What gets externalised from the server render [#what-gets-externalised-from-the-server-render]

You do not write an `ssr.external` list, because the right answer changes
between the two commands:

| Command      | `@vitnode/core` and your plugins | Why                                                                               |
| ------------ | -------------------------------- | --------------------------------------------------------------------------------- |
| `vite dev`   | inlined                          | Vite owns the modules, so a rebuilt package reaches the server render immediately |
| `vite build` | external                         | the built package goes into the output as it is, rather than being bundled again  |

Externalising in dev is the tempting mistake, and it fails quietly: an external
module is imported by Node, whose module cache lives as long as the process. The
browser hot-reloads your edit, the server render keeps the copy it loaded at
startup, and React reports a hydration mismatch on markup you already fixed. Only
a restart clears it - which is exactly the loop this plugin removes.

The build list is `@vitnode/core`, every plugin in your `vitnode.config.ts` and
`tslib`. It comes from the same configured plugin list the route generator reads,
so removing a plugin from your config is one edit, not two.

### Which files Tailwind scans [#which-files-tailwind-scans]

You do not write `@source` lines for VitNode packages either. Tailwind only
generates a utility it has seen spelled out somewhere, and the components that
ship inside `@vitnode/core` and your plugins live in `node_modules`, which
Tailwind skips by default. So the plugin appends one `@source` per package to
every stylesheet that imports Tailwind:

```css title="what your styles.css effectively becomes"
@import 'tailwindcss';

@source "<app>/node_modules/@vitnode/core/dist/src/**/*.js";
@source "<app>/node_modules/@acme/blog/dist/src/**/*.js";
```

The list is `@vitnode/core` plus every plugin in your `vitnode.config.ts`, and it
covers each package's whole build output. Installing a plugin is therefore still
one edit: its styles work the moment it is configured.

This one fails quietly in a way worth recognising, because nothing errors. The
class name lands in the DOM and hot reloading works perfectly - the element just
has no styling, and reloading the page does not help, because the rule was never
generated. If you ever see that for a package of your own, it is missing from the
scan, not broken.

## Learn More [#learn-more]

# Contributing (/docs/dev/contribution)

Contributions to VitNode - whether bug fixes, new features, or documentation improvements - are always welcome!

## Quick start [#quick-start]

Clone the repository, start local containers, and launch the dev server:

```bash tab="bun"
bun install
bun run docker:dev
bun dev
```

```bash tab="pnpm"
pnpm install
pnpm docker:dev
pnpm dev
```

```bash tab="npm"
npm install
npm run docker:dev
npm run dev
```

</Tabs>

Open `http://localhost:3000` to view the website, AdminCP, and live docs.

---

## Monorepo Layout [#monorepo-layout]

| Directory | Role |
| :--- | :--- |
| `packages/vitnode` | `@vitnode/core` package containing routing, auth, models, and UI primitives |
| `apps/web` | Frontend TanStack Start application and documentation portal |
| `apps/api` | Standalone Hono REST/RPC API server |
| `plugins/*` | First-party plugins (`@vitnode/blog`, `@vitnode/example`) |

---

## Local Validation Checks [#local-validation-checks]

Before opening a pull request, run the same checks that execute in GitHub Actions CI:

### 1. Typecheck [#1-typecheck]

```bash tab="bun"
bun run typecheck
```

```bash tab="pnpm"
pnpm typecheck
```

```bash tab="npm"
npm run typecheck
```

</Tabs>

### 2. Run Tests [#2-run-tests]

```bash tab="bun"
bun test
```

```bash tab="pnpm"
pnpm test
```

```bash tab="npm"
npm test
```

</Tabs>

### 3. Build All Workspaces [#3-build-all-workspaces]

```bash tab="bun"
bun run build
```

```bash tab="pnpm"
pnpm build
```

```bash tab="npm"
npm run build
```

</Tabs>

---

## Docs for AI Agents [#docs-for-ai-agents]

The documentation portal in `apps/web` speaks Markdown as well as HTML, so agents and LLM tools can read it without scraping:

Requesting a docs page with an `Accept: text/markdown` header redirects to its `.md` twin, so a curious agent gets Markdown without asking twice. Every page also has a **Copy Markdown** button and an **Open in** menu for ChatGPT, Claude and friends.

---

## Pull Request Guidelines [#pull-request-guidelines]

1. **Focused PRs**: Keep changes scoped to a single feature or bug fix.
2. **Follow Conventions**: Follow repository conventions from `AGENTS.md` (no `any`, arrow function components, semantic tokens).
3. **Tests**: Add unit tests for non-trivial logic using Vitest.

## Learn More [#learn-more]

# Custom Adapter (/docs/dev/cron/custom-adapter)

A cron adapter is the thinnest interface in VitNode: one method, no return value,
called once while the API boots. Its whole job is to call `handleCronJobs()` on a
clock. Everything else - which jobs exist, which are due, what gets logged - is
the [cron endpoint](/docs/dev/cron/rest-api)'s business, not the adapter's.

Write one when the [Node CRON adapter](/docs/dev/cron/node-cron) is not the
scheduler you want: you already run a job runner, you need the tick to carry a
trace header, or the platform hands you a trigger of its own.

## Quick start [#quick-start]

The shortest adapter that works is a timer:

```ts title="src/adapters/interval-cron.adapter.ts"
import { type CronAdapter, handleCronJobs } from '@vitnode/core/api/lib/cron'

export const IntervalCronAdapter = (): CronAdapter => ({
  schedule() {
    setInterval(() => {
      handleCronJobs().catch((error: unknown) => {
        console.error('[cron] tick failed', error)
      })
    }, 60_000)
  },
})
```

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

import { IntervalCronAdapter } from './adapters/interval-cron.adapter' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  cron: IntervalCronAdapter(), // [!code ++]
  // ...
})
```

That is a complete, working adapter. The rest of this page is about doing it with
a real scheduler, and about the ways it can go quietly wrong.

## The interface [#the-interface]

```ts title="packages/vitnode/src/api/lib/cron.ts"
export interface CronAdapter {
  schedule: () => void
}
```

<TypeTable
  type={{
    schedule: {
      description:
        'Called once by VitNodeAPI while the application is being built, before any request is served. Register your timer or trigger here. Synchronous and void - nothing awaits it and nothing catches it.',
      type: '() => void',
      required: true,
    },
  }}
/>

`handleCronJobs()` comes from the same module and takes no arguments. It posts to
`/api/@vitnode/core/cron` on the origin in `VITNODE_API_URL` (falling back to
`http://localhost:3000`) with `Content-Type: application/json` and
`Authorization: Bearer $CRON_SECRET`. It resolves as soon as the response
arrives and never looks at it, so a `403` or a `500` resolves exactly like a
`200` - only a network-level failure rejects.

<Callout type="info" title="You do not have to use handleCronJobs">
  It is a convenience, not a contract. An adapter whose scheduler lives outside
  the process - a platform trigger, a separate worker - can leave `schedule()`
  empty and let that scheduler [call the endpoint
  directly](/docs/dev/cron/rest-api). The adapter still earns its place: setting
  `cron` is what makes the AdminCP report a scheduler as configured.
</Callout>

## Build one with a library [#build-one-with-a-library]

### Write the adapter [#write-the-adapter]

Keep it in your app rather than in a plugin - a cron adapter is a deployment
decision, and it is registered from the API config, which only the host has.

The official package is the reference implementation, and it is short enough to
read in one go:

```ts title="src/adapters/node-cron.adapter.ts"
import { type CronAdapter, handleCronJobs } from '@vitnode/core/api/lib/cron'
import { schedule } from 'node-cron'

export const NodeCronAdapter = (): CronAdapter => {
  return {
    schedule() {
      schedule('*/1 * * * *', async () => {
        await handleCronJobs() // [!code highlight]
      })
    },
  }
}
```

Give the factory options if your scheduler has any worth exposing - a tick
interval, a timezone, a logger. `CronAdapter` says nothing about the factory, so
its signature is yours.

</Step>
<Step>

### Register it in the API config [#register-it-in-the-api-config]

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

import { NodeCronAdapter } from './adapters/node-cron.adapter' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  cron: NodeCronAdapter(), // [!code ++]
  // ...
})
```

</Step>
<Step>

### Restart and verify the first tick [#restart-and-verify-the-first-tick]

`schedule()` runs at boot, so a running process never picks up the change.

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

Open `/admin/core/advanced/cron` and watch the `process-queue` row - it is
scheduled `* * * * *`, so a healthy adapter keeps its **Last Run** under a minute
old. If it stays on _Never_, your `schedule()` ran but your tick is not landing:
check the origin, then the secret, then whether the API can reach itself.

</Step>
</Steps>

## Gotchas [#gotchas]

<Callout type="warn" title="A throw in schedule() takes the API down">
  VitNode calls `schedule()` synchronously while building the application and
  does not wrap it. An adapter that validates its own options by throwing turns
  a bad cron expression into a server that will not start. Validate, log, and
  return instead.
</Callout>

<Callout
  type="warn"
  title="schedule() can be called more than once per process"
>
  There is no `stop` and no teardown hook, and a dev server that re-evaluates
  its server modules can build the API again. VitNode's TanStack Start app parks
  the API instance on `globalThis` for exactly this reason - if yours does not,
  an adapter that keeps a timer should be able to notice it already has one
  instead of stacking a second.
</Callout>

<Callout type="warn" title="Ticking faster does not make a job faster">
  The endpoint runs what is due when it is called, so the tick interval is the
  floor on every job's resolution - but it is not a speed control. A tick every
  ten seconds on jobs that are all `*/5 * * * *` is five wasted requests a
  minute, and a tick every five minutes silently downgrades `* * * * *` jobs,
  [queue draining](/docs/dev/advanced/queue) included.
</Callout>

<Callout
  type="warn"
  title="Overlapping ticks are your problem, not the adapter's"
>
  Nothing locks a job while it runs. If your scheduler can fire again before the
  previous tick's handlers have finished, the same handler can be running twice.
  [The operational rules](/docs/dev/cron#jobs-must-be-idempotent) cover what to
  do about it.
</Callout>

## Next [#next]

# Cron Jobs (/docs/dev/cron)

A cron job in VitNode consists of a named handler and a standard 5-field cron expression. Cron definitions are automatically registered in the `core_cron` database table and manageable through the AdminCP.

## Quick start [#quick-start]

### 1. Define a Cron Job [#1-define-a-cron-job]

Create a cron definition in your plugin:

```ts title="plugins/blog/src/api/cron/cleanup.cron.ts"
import { buildCron } from '@vitnode/core/api/lib/cron'

export const cleanupCron = buildCron({
  name: 'cleanup-drafts',
  description: 'Remove expired post drafts every midnight',
  schedule: '0 0 * * *', // Standard cron syntax
  handler: async (c) => {
    await c.get('log').info('Running midnight cleanup...')
  },
})
```

---

### 2. Register in an API Module [#2-register-in-an-api-module]

Attach the cron job to a module in `src/api/modules/`:

```ts title="plugins/blog/src/api/modules/posts/posts.module.ts"
import { buildModule } from '@vitnode/core/api/lib/module'
import { cleanupCron } from '../../cron/cleanup.cron'

export const postsModule = buildModule({
  name: 'posts',
  routes: [listPostsRoute],
  cronJobs: [cleanupCron], // [!code ++]
})
```

When your plugin is mounted in `config.api.ts`, the cron job is automatically registered.

---

## Execution Adapters [#execution-adapters]

VitNode does not hold persistent timers in the HTTP worker. Instead, jobs are triggered via an adapter:

### Option A: In-Process Node CRON (Single Server) [#option-a-in-process-node-cron-single-server]

Best for single-instance or local development. Configure in `vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { NodeCronAdapter } from '@vitnode/node-cron'
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  cron: NodeCronAdapter(), // [!code ++]
})
```

### Option B: External Webhook (Multi-Instance / Serverless) [#option-b-external-webhook-multi-instance--serverless]

Trigger runs via external HTTP schedulers (AWS EventBridge, GitHub Actions, or crontab):

```bash
curl -X POST https://your-domain.com/api/@vitnode/core/cron   -H "Authorization: Bearer $CRON_SECRET"
```

---

## AdminCP Management [#admincp-management]

{/* Image prompt: VitNode AdminCP Cron management page at /admin/core/advanced/cron. Data table displaying scheduled jobs with columns: Name, Schedule, Status, Last Run, Next Run, and an action button "Run Now". Dark theme, 1440x900. */}

Manage and inspect cron jobs in the AdminCP at **Core → Advanced → Cron Jobs** (`/admin/core/advanced/cron`):

- View status, schedules, and last execution logs.
- Click **Run Now** to execute any job manually on demand.

### Health warnings [#health-warnings]

Cron fails quietly by nature: nobody notices a job that didn't run. So VitNode watches for it.

A job is **overdue** when its next scheduled run is more than 15 minutes in the past. Never-run jobs count from the moment they were registered.

The scheduler card at the top of the page sums it up:

| What you see | What it means |
| --- | --- |
| Red **Scheduler stopped** | A job is overdue and nothing has run since. The scheduler is stopped or misconfigured, and the queue isn't draining either. |
| Amber **N cron jobs are overdue** | The scheduler ticks, but some jobs aren't finishing. A job that throws keeps its last successful run, so look for its error in the server logs. |
| Green **All jobs on schedule** | Everything ran on time. Go make a coffee. |

Next to it you get the last run, the next run and how many jobs are registered. The table below lists every job with an **Overdue**, **On schedule** or **Waiting for first run** status.

The same check powers the **Cron Jobs** and **Queue Tasks** cards at **Core → System → Integrations**.

---

## `buildCron` Options [#buildcron-options]

<TypeTable
  type={{
    name: {
      description:
        "Unique identifier within the plugin (e.g. 'cleanup-drafts').",
      required: true,
      type: 'string',
    },
    schedule: {
      description: 'Standard 5-part cron pattern (minute hour dom month dow).',
      required: true,
      type: 'string',
    },
    handler: {
      description: 'Async function executed when the job is triggered.',
      required: true,
      type: '(c: Context) => Promise<void>',
    },
    description: {
      description: 'Human-readable purpose shown in AdminCP list.',
      type: 'string',
    },
  }}
/>

## Learn More [#learn-more]

# Node CRON (/docs/dev/cron/node-cron)

`@vitnode/node-cron` is the in-process [cron adapter](/docs/dev/cron): a
[node-cron](https://www.npmjs.com/package/node-cron) timer that lives inside your
API process and posts to the cron endpoint once a minute. No external service, no
scheduler dashboard, nothing to keep in sync - which is exactly why it only works
where your API is a long-lived process.

| Cloud (serverless) | Self-hosted  | Links                                                                                                                                       |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| ❌ Not supported   | ✅ Supported | [npm](https://www.npmjs.com/package/@vitnode/node-cron) · [source](https://github.com/aXenDeveloper/vitnode/tree/canary/packages/node-cron) |

## Quick start [#quick-start]

### Install the adapter [#install-the-adapter]

```bash tab="bun"
bun i @vitnode/node-cron
```

```bash tab="pnpm"
pnpm i @vitnode/node-cron
```

```bash tab="npm"
npm i @vitnode/node-cron
```

</Tabs>

A runtime dependency, not a dev one - the adapter is imported by the server that
serves your API, so it has to survive a production install.

</Step>
<Step>

### Register it in the API config [#register-it-in-the-api-config]

`NodeCronAdapter()` takes no arguments. There is nothing to configure, because
the schedule it keeps is not yours: each job carries its own expression, and this
only decides how often VitNode looks.

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { NodeCronAdapter } from '@vitnode/node-cron' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  cron: NodeCronAdapter(), // [!code ++]
  // ...
})
```

This repository's own standalone API does exactly that - see
`apps/api/src/vitnode.api.config.ts`.

</Step>
<Step>

### Restart the server [#restart-the-server]

`schedule()` is a boot step, not a request step: VitNode calls it once while the
API is being built, so a running process never picks the adapter up.

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

</Step>
<Step>

### Verify the first tick [#verify-the-first-tick]

Open `/admin/core/advanced/cron` and watch the `clean` row - core's hourly
session cleanup, which every installation has. Within a minute of the restart
**Last Run** stops saying _Never_ and **Next Run** fills in.

Nothing else needs to happen for the clock to be proven: `process-queue` runs
every minute, so its **Last Run** should never be more than a minute old while
the adapter is alive.

</Step>
</Steps>

## What the adapter actually does [#what-the-adapter-actually-does]

The whole package is the file below, and knowing it saves an afternoon of
debugging:

```ts title="packages/node-cron/src/index.ts"
import { type CronAdapter, handleCronJobs } from '@vitnode/core/api/lib/cron'
import { schedule } from 'node-cron'

export const NodeCronAdapter = (): CronAdapter => {
  return {
    schedule() {
      schedule('*/1 * * * *', async () => {
        await handleCronJobs()
      })
    },
  }
}
```

`handleCronJobs()` is an **HTTP request to your own API** -
`POST /api/@vitnode/core/cron`, with `Content-Type: application/json` and
`Authorization: Bearer $CRON_SECRET`. The adapter never touches the database and
never calls a job handler; it only knocks on the door once a minute, and the
[cron endpoint](/docs/dev/cron/rest-api) decides what is due.

Three consequences worth writing down:

| Because the tick is an HTTP call…                     | …this is true                                                                          |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| it needs a URL                                        | the origin comes from `VITNODE_API_URL`, falling back to `http://localhost:3000`       |
| the API must be able to reach itself over the network | a tick dies where that origin is wrong, unreachable, or fronted by an auth proxy       |
| the request is authenticated like any other           | an unset `CRON_SECRET` means both sides use the well-known default, and the tick works |

## Gotchas [#gotchas]

<Callout
  type="warn"
  title="The tick posts to VITNODE_API_URL, not to the port you booted"
>
  `handleCronJobs()` builds its URL from `VITNODE_API_URL` and falls back to
  `http://localhost:3000`. This repo's standalone API listens on **8000** -
  which is exactly why `apps/api/.env.example` sets the variable - so leaving it
  unset sends every tick to port 3000, where the web app lives. Symptom: the
  scheduler is configured, the boot log is clean, and **Last Run** stays _Never_
  forever.
</Callout>

<Callout type="warn" title="A rejected tick leaves no trace">
  `handleCronJobs()` awaits the `fetch` and then discards the response, and a
  `403` is answered by middleware rather than by the route: the CSRF check runs
  before the logger even exists, and a mismatched secret raises an
  `HTTPException` that the API's error handler returns without logging. So the
  failure you are most likely to hit writes nothing to the console and nothing
  to the [Debug Panel](/docs/dev/debugging/logging). The AdminCP's **Last Run**
  column is the health check.
</Callout>

<Callout type="warn" title="Every instance runs its own timer">
  The adapter schedules per process, so four instances send four ticks a minute.
  That is safe - the endpoint runs only what is due - but it does not
  de-duplicate the work, so two ticks can start the same job at once. Write
  [idempotent handlers](/docs/dev/cron#jobs-must-be-idempotent), or move the
  clock to a single [external scheduler](/docs/dev/cron/rest-api).
</Callout>

<Callout type="warn" title="Serverless has nowhere to keep the timer">
  A function that is frozen between requests cannot hold a one-minute interval,
  so this adapter is not a deployment choice on Vercel-style hosting - it is a
  no-op with a package to maintain. Use the [REST
  endpoint](/docs/dev/cron/rest-api) there.
</Callout>

## Next [#next]

# Cron over REST (/docs/dev/cron/rest-api)

Every cron run in VitNode is one HTTP request, so the simplest adapter is no
adapter at all: point something at the endpoint once a minute. That something can
be GitHub Actions, a managed scheduler, a Kubernetes `CronJob` or a systemd
timer. Because it lives outside your app, this is also the only option that works
on serverless hosting, where nothing stays alive long enough to hold a timer.

| Cloud (serverless) | Self-hosted  |
| ------------------ | ------------ |
| ✅ Supported       | ✅ Supported |

## Quick start [#quick-start]

```bash
curl -X POST https://example.com/api/@vitnode/core/cron \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CRON_SECRET"
```

```text
Cron jobs processed. Executed 2 jobs.
```

Both headers are load-bearing. The `Authorization` one is the endpoint's only
auth; the `Content-Type` one gets you past CSRF protection, which treats a
`POST` with no content type as a form submission and answers `403 Forbidden`.

## Set it up [#set-it-up]

### Set a real CRON_SECRET [#set-a-real-cron_secret]

The endpoint compares the bearer token against `CRON_SECRET` and refuses
anything else with a `403`. Leave the variable unset and VitNode falls back to
`default-cron-secret-change-in-production` - a value published in this
documentation, which makes the endpoint effectively open to anyone who can guess
your domain.

```bash title=".env"
CRON_SECRET=b7c1f0e2d9a84c53b6e1f7a02d48c9e5
```

<Callout
  type="warn"
  title="This is the one secret an external scheduler carries"
>
  Use at least 16 random characters, and store it in your scheduler as a secret
  rather than in a URL. Do not expect the AdminCP to nag you about it: the
  Integrations screen only reports the default secret once a `cron` adapter is
  registered in the API config, and an external scheduler registers none - so
  the cron card there says "No cron adapter configured" and stops. On this
  deployment shape, remembering the secret is on you.
</Callout>

</Step>
<Step>

### Point a scheduler at the endpoint [#point-a-scheduler-at-the-endpoint]

Once a minute, whatever the schedules on your jobs say. The endpoint runs what is
due _at the moment it is called_, so the tick interval is the finest resolution
any job can have - and core's own `process-queue` job is `* * * * *`, so a
slower tick means [queue tasks](/docs/dev/advanced/queue) sit around waiting.

Your scheduler needs three things, and this is where providers differ:

| Requirement                     | Why                                                        |
| ------------------------------- | ---------------------------------------------------------- |
| `POST`                          | the route declares `method: "post"` and nothing else       |
| a custom `Authorization` header | the bearer token is the whole of the auth                  |
| a custom `Content-Type` header  | `application/json`, or CSRF protection rejects the request |

{/* Image prompt: A generic external cron scheduler's "new job" form, light theme, 1200x800, showing the four fields a reader has to fill in: URL set to https://example.com/api/@vitnode/core/cron, method dropdown set to POST, a schedule field reading "every minute", and a custom-headers table with two rows - "Content-Type: application/json" and "Authorization: Bearer ***". No real vendor branding. */}

A GitHub Actions workflow is the version with no account to create:

```yaml title=".github/workflows/cron.yml"
name: VitNode cron
on:
  schedule:
    - cron: '*/5 * * * *'
  workflow_dispatch:

jobs:
  tick:
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl --fail-with-body -X POST "$API_URL/api/@vitnode/core/cron" \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer $CRON_SECRET"
        env:
          API_URL: ${{ vars.API_URL }}
          CRON_SECRET: ${{ secrets.CRON_SECRET }}
```

Five minutes, not one: GitHub's shortest schedule interval is five minutes, and
runs on a busy shared queue are often later than that. It is a fine way to keep
daily jobs honest and a poor way to drain a queue.

</Step>
<Step>

### Verify it from the AdminCP [#verify-it-from-the-admincp]

Send the request by hand once. A `200` with a job count means the endpoint
accepted you; open `/admin/core/advanced/cron` and the rows you expected to run
now show a **Last Run** of a moment ago.

Then leave the scheduler to it and check back. **Last Run** drifting behind a
job's schedule is the symptom of a tick that is not arriving, and it is the only
signal that reflects an external scheduler - see the gotcha about the
Integrations screen below.

</Step>
</Steps>

## Endpoint reference [#endpoint-reference]

| Property         | Value                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| Method           | `POST`                                                                                                       |
| Path             | `/api/@vitnode/core/cron`                                                                                    |
| Auth             | `Authorization: Bearer $CRON_SECRET` - the prefix is stripped before comparing, so a bare secret matches too |
| Body             | none                                                                                                         |
| Calling it twice | safe: the second call runs only what has become due since the first                                          |

| Response | Body                                    | Means                                                                                               |
| -------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `200`    | `Cron jobs processed. Executed N jobs.` | the tick completed; `N` counts the jobs whose handler did **not** throw                             |
| `403`    | `Forbidden`                             | CSRF: a `POST` whose content type is missing, `text/plain` or a form type, with no trusted `Origin` |
| `403`    | `Invalid cron authorization`            | the bearer token does not match `CRON_SECRET`                                                       |
| `500`    | `Error processing cron jobs`            | the bookkeeping itself failed - usually the database                                                |

## Gotchas [#gotchas]

<Callout type="warn" title="Vercel Cron Jobs cannot call this endpoint">
  Vercel triggers a cron path with a `GET`; this route only answers `POST`, so a
  `vercel.json` entry pointed straight at it never runs a job. Use a scheduler
  that can send a `POST` with headers - the [Vercel deployment
  guide](/docs/dev/deployments/cloud/vercel) says the same thing from the other
  side.
</Callout>

<Callout type="warn" title="A 200 does not mean every job succeeded">
  A handler that throws is logged and skipped - the tick still answers `200`,
  and the failed job is simply missing from the count. Worse, its `lastRun` is
  not written, so it is due again on the next tick. Read the failures in the
  [Debug Panel](/docs/dev/debugging/logging); the response only tells you the
  endpoint was reached.
</Callout>

<Callout type="warn" title="Ticking from two places doubles the ticks">
  An external scheduler and the [Node CRON adapter](/docs/dev/cron/node-cron)
  are alternatives, not layers. Configure both and two callers race for the same
  due jobs, which is the situation [idempotent
  handlers](/docs/dev/cron#jobs-must-be-idempotent) exist for.
</Callout>

<Callout type="warn" title="The Integrations screen still calls cron inactive">
  `/admin/core/system/integrations` reports cron as active when the API config
  registers a `cron` adapter - it is reading the config, not counting ticks.
  Tick from outside and that card stays grey however healthy the schedule is,
  and the queue card with it, because the queue's status is derived from cron's.
  The honest signal for an external scheduler is the **Last Run** column on
  `/admin/core/advanced/cron`.
</Callout>

<Callout
  type="info"
  title="The endpoint is public in the sense that it answers"
>
  There is no allowlist and no signature - a correct bearer token is the whole
  gate, and the route is mounted on your public API alongside everything else.
  If your platform can restrict the path to your scheduler's egress addresses,
  that is a second lock worth having.
</Callout>

## Next [#next]

# Database & Migrations (/docs/dev/database)

VitNode uses [PostgreSQL](https://www.postgresql.org) and [Drizzle ORM](https://orm.drizzle.team). Plugins define typed schema files, compile them into SQL migrations, and query tables via `c.get("db")`.

## Quick start [#quick-start]

### 1. Define the Schema [#1-define-the-schema]

Create a database model in `plugins/{plugin}/src/database/{table}.ts`:

```ts title="plugins/reactions/src/database/reactions.ts"
import { camelCase } from "drizzle-orm/pg-core"

// [!code ++:7]
export const reactions = camelCase.table.withRLS("reactions", (t) => ({
  id: t.serial().primaryKey(),
  itemId: t.integer().notNull(),
  emoji: t.varchar({ length: 32 }).notNull(),
  createdAt: t.timestamp().notNull().defaultNow(),
}))
```

---

### 2. Query in an API Route [#2-query-in-an-api-route]

Access the typed Drizzle instance using `c.get("db")`:

```ts title="plugins/reactions/src/api/modules/reactions/routes/get.route.ts"
import { buildRoute } from "@vitnode/core/api/lib/route"
import { reactions } from "@/database/reactions"

export const getReactionsRoute = buildRoute({
  pluginId: "reactions",
  route: {
    method: "get",
    path: "/",
    responses: { 200: { description: "List of reactions" } },
  },
  handler: async (c) => {
    // [!code ++:2]
    const rows = await c.get("db").select().from(reactions)
    return c.json(rows)
  },
})
```

---

### 3. Build & Apply Migrations [#3-build--apply-migrations]

```bash tab="bun"
bun run build:plugins && bun run db:migrate
```

```bash tab="pnpm"
pnpm build:plugins && pnpm db:migrate
```

```bash tab="npm"
npm run build:plugins && npm run db:migrate
```

</Tabs>

`build:plugins` compiles your TypeScript models and exports, and `db:migrate` updates PostgreSQL.

---

## Migration Commands [#migration-commands]

Run these with the [VitNode CLI](/docs/dev/cli/database) in the app that owns the database:

<Callout type="info" title="Content Engine Alternative">
  If your table represents an editorial entity (articles, FAQs, products), consider [Content Engine](/docs/content-engine/create-a-content-type) to generate your Drizzle table, API routes, and AdminCP screens from one definition.
</Callout>

## Connection pool [#connection-pool]

VitNode talks to Postgres through [`postgres.js`](https://github.com/porsager/postgres), and the default config hands it a bare connection string:

```ts title="src/vitnode.api.config.ts"
dbProvider: drizzle({
  connection: POSTGRES_URL,
  relations: coreRelations,
}),
```

That means `postgres.js` defaults: up to **10** connections per process, idle connections kept **forever** (`idle_timeout: 0`), and automatic prepared statements (`prepare: true`). Perfectly fine on your laptop. In production you probably want to pick the numbers yourself.

Swap the string for an object - `url` plus any [`postgres.js` option](https://github.com/porsager/postgres#all-postgres-options):

### Long-running server [#long-running-server]

A Node server, a Docker container, a VPS. One process lives for days and handles plenty of requests at once, so give it room:

```ts title="src/vitnode.api.config.ts"
dbProvider: drizzle({
  connection: POSTGRES_URL, // [!code --]
  connection: { url: POSTGRES_URL, max: 20, idle_timeout: 20 }, // [!code ++]
  relations: coreRelations,
}),
```

**Sizing rule of thumb:** every process opens its own pool, and Postgres has a hard ceiling (`SHOW max_connections;` - often `100`). So:

```text
max ≈ (max_connections − headroom) ÷ number of processes
```

Keep 10-20 connections of headroom for migrations, `db:studio`, backups and you poking around in `psql`. With `max_connections = 100`, 4 instances and 20 spare, that is `max: 20` each. Scale out to 8 instances and the same math says `max: 10` - forget to redo it and the fifth instance greets you with `too many connections`.

### Serverless [#serverless]

On Vercel, Netlify and friends every concurrent request may be its own process, so `max × processes` grows faster than you would like. Use your provider's pooled connection string, or keep each process to a single connection with `max: 1`. The [Vercel guide](/docs/dev/deployments/cloud/vercel#bring-a-managed-postgres) has the full setup.

### Behind a transaction pooler [#behind-a-transaction-pooler]

<Callout type="warn" title="Set prepare: false for transaction-mode poolers">
  The Supabase pooler on port `6543`, PgBouncer with `pool_mode = transaction`
  and similar poolers hand you a different backend connection for every
  transaction. A prepared statement created on one backend does not exist on
  the next, so queries fail at random with `prepared statement "..." does not
  exist`. Turn automatic prepared statements off:

```ts title="src/vitnode.api.config.ts"
dbProvider: drizzle({
  connection: { url: POSTGRES_URL, prepare: false },
  relations: coreRelations,
}),
```

</Callout>

Direct connections and session-mode poolers keep `prepare: true` - it is the faster option. VitNode's own locks are transaction-scoped (`pg_advisory_xact_lock`), so they work behind either mode.

## Learn More [#learn-more]

# Pagination (/docs/dev/database/pagination)

VitNode pages with cursors by default. Cursors keep page boundaries stable even while records are created or deleted, and they cost the same whether you are on page 2 or page 20,000.

When a list needs numbered pages — 1, 2, 3 … 38, the kind admin tables show — the same route also accepts `?page=`. You do not have to choose up front: one route serves both.

## Quick start [#quick-start]

### Add a paginated API route [#add-a-paginated-api-route]

Use `withPagination` from `@vitnode/core/api/lib/with-pagination`:

```ts title="plugins/blog/src/api/modules/posts/routes/get.route.ts"
import { getColumns } from 'drizzle-orm'
import {
  withPagination,
  zodPaginationQuery,
} from '@vitnode/core/api/lib/with-pagination'
import { blog_posts } from '@/database/posts'

export const getPostsRoute = buildRoute({
  pluginId: 'blog',
  route: {
    method: 'get',
    path: '/',
    request: {
      query: zodPaginationQuery,
    },
  },
  handler: async (c) => {
    const data = await withPagination({
      c,
      params: { query: c.req.valid('query') },
      primaryCursor: blog_posts.id,
      table: blog_posts,
      orderBy: { column: blog_posts.createdAt, order: 'desc' },
      query: async ({ cursorSelection, limit, offset, where, orderBy }) =>
        await c
          .get('db')
          .select({ ...getColumns(blog_posts), ...cursorSelection })
          .from(blog_posts)
          .where(where)
          .orderBy(orderBy)
          .limit(limit)
          .offset(offset),
    })

return c.json(data)
  },
})
```

The route automatically accepts `?cursor=...&first=10` (cursor walk) or `?page=3&first=10` (numbered page), and returns `{ edges, pageInfo }`.

<Callout type="warn">
  Always spread `offset` into the statement. Without it, `?page=` silently
  returns the first page over and over.
</Callout>

</Step>
</Steps>

## Cursors or numbered pages? [#cursors-or-numbered-pages]

| Metric                        | `?page=` (offset)               | `?cursor=` (keyset)                    |
| ----------------------------- | ------------------------------- | -------------------------------------- |
| Insert / Delete mid-walk      | Rows shift, duplicate, or skip  | Unaffected (stable pointer)            |
| Deep pagination (page 10,000) | Walks every skipped row         | Single indexed B-tree lookup           |
| Sort order stability          | Prone to non-deterministic ties | Guaranteed by primaryCursor tiebreaker |
| Jump to an arbitrary page     | Yes                             | No — you can only step                 |
| "Page 4 of 38"                | Yes                             | No — there is no page number           |

Rule of thumb: **numbered pages for admin tables**, where people want page 7 and the lists are short; **cursors for public feeds and infinite scroll**, where depth is unbounded and nobody counts pages.

### Index the column you order by [#index-the-column-you-order-by]

Both modes need an index on the ordered tuple, and neither is fast without one:

```ts title="plugins/blog/src/database/posts.ts"
index('blog_posts_created_at_id_idx').on(t.createdAt, t.id)
```

The cursor predicate is emitted as a row comparison — `(createdAt, id) < ($1, $2)` — precisely so Postgres can seek straight to the boundary on that index. Measured on a million rows, the seek reaches the hundred-thousandth row in 0.19ms. Without the index, the same query scans and sorts the whole table on every page.

---

## `withPagination` Options [#withpagination-options]

<TypeTable
  type={{
    c: {
      description: 'Hono request context.',
      required: true,
      type: 'Context',
    },
    params: {
      description:
        'Validated query parameters: { query: { cursor, first, last, page, search } }.',
      required: true,
      type: 'object',
    },
    table: {
      description: 'Drizzle table being paged (used for total count).',
      required: true,
      type: 'PgTable',
    },
    primaryCursor: {
      description:
        'Integer, bigint or UUID row identifier acting as deterministic tiebreaker.',
      required: true,
      type: 'PaginationCursorColumn',
    },
    orderBy: {
      description: 'Sorting column and direction.',
      required: true,
      type: "{ column: PgColumn; order: 'asc' | 'desc' }",
    },
    query: {
      description: 'Callback executing the paged Drizzle select query.',
      required: true,
      type: '(args) => Promise<Row[]>',
    },
    where: {
      description:
        'Additional SQL filter conditions applied before pagination.',
      required: false,
      type: 'SQL',
    },
    search: {
      description:
        'Array of text columns to match against ?search= with ILIKE.',
      required: false,
      type: 'PgColumn[]',
    },
  }}
/>

---

## Integer, bigint and UUID identifiers [#integer-bigint-and-uuid-identifiers]

`primaryCursor` accepts integer, bigint and UUID columns. Bigints travel as
decimal strings inside the opaque cursor, so values above JavaScript's
safe-integer limit keep their precision. UUIDs stay strings and are validated
before they reach PostgreSQL.

The order column and the identifier can use different types. A bigint order
column can take a UUID primary key as its stable tiebreaker:

```ts
import { bigint, pgTable, uuid } from 'drizzle-orm/pg-core'

const events = pgTable('events', {
  id: uuid().defaultRandom().primaryKey(),
  sequence: bigint({ mode: 'bigint' }).notNull(),
})

await withPagination({
  // ...
  primaryCursor: events.id,
  orderBy: { column: events.sequence, order: 'asc' },
})
```

Keep the cursor opaque on the client and hand it back unchanged in the next
request.

---

## Response Structure (`pageInfo`) [#response-structure-pageinfo]

```json
{
  "edges": [
    { "id": 1, "title": "First post", "createdAt": "2026-01-01T00:00:00.000Z" }
  ],
  "pageInfo": {
    "totalCount": 120,
    "totalPages": 12,
    "currentPage": 1,
    "count": 10,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "eyJjIjoiY3Jl...",
    "endCursor": "eyJjIjoiY3Jl..."
  }
}
```

---

## Frontend Integration [#frontend-integration]

### Move through results from a plugin page [#move-through-results-from-a-plugin-page]

Plugin routes normalize their own query string with `parseSearch`, then receive
the typed `search`, `loaderData`, and same-page `navigate` function. That is all
a list needs—no host route file required.

```tsx title="plugins/blog/src/pages/posts-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
import { definePluginRoute } from '@vitnode/core/routing'

interface PostsSearch {
  cursor?: string
  first: number
}

// [!code ++:11]
export const route = definePluginRoute({
  parseSearch: (input) => {
    const search = input as Record<string, unknown>
    const first = Number(search.first)

return {
      cursor: typeof search.cursor === 'string' ? search.cursor : undefined,
      first: Number.isInteger(first) && first > 0 ? first : 10,
    }
  },
  load: async ({ search }) => await fetchPosts(search),
})

const PostsPage = ({
  loaderData,
  navigate,
  search,
}: PluginRoutePageProps<
  Awaited<ReturnType<typeof fetchPosts>>,
  PostsSearch
>) => (
  <button
    disabled={!loaderData.pageInfo.hasNextPage}
    onClick={() =>
      void navigate({
        resetScroll: false,
        search: {
          ...search,
          cursor: loaderData.pageInfo.endCursor ?? undefined, // [!code ++]
        },
      })
    }
    type="button"
  >
    Next page
  </button>
)

export default PostsPage
```

</Step>
</Steps>

## Custom Filtering and Search [#custom-filtering-and-search]

To add search and custom filters, pass the parameters into `withPagination`:

```ts title="plugins/blog/src/api/modules/posts/routes/get.route.ts"
import { eq } from 'drizzle-orm'

const data = await withPagination({
  c,
  params: { query: c.req.valid('query') },
  table: blog_posts,
  primaryCursor: blog_posts.id,
  orderBy: { column: blog_posts.createdAt, order: 'desc' },
  // [!code ++:3]
  search: [blog_posts.title, blog_posts.content],
  where: categoryId ? eq(blog_posts.categoryId, categoryId) : undefined,
  query: async ({ cursorSelection, limit, where, orderBy }) =>
    await c
      .get('db')
      .select({ ...getColumns(blog_posts), ...cursorSelection })
      .from(blog_posts)
      .where(where)
      .orderBy(orderBy)
      .limit(limit),
})
```

---

## Best Practices [#best-practices]

<Callout type="info" title="Opaque cursors">
  Cursors encode the specific column ordering. If the user changes sort order or
  filter criteria, reset the cursor to `undefined` so pagination starts from the
  first page.
</Callout>

<Callout type="warn" title="Always apply callback where and orderBy">
  `withPagination` injects cursor conditions directly into the callback's
  `where` and `orderBy`. Always pass those arguments straight to Drizzle's query
  methods without rebuilding them.
</Callout>

## Learn More [#learn-more]

# Search (/docs/dev/database/search)

`withPagination` includes built-in multi-column search filtering. When `search` columns are specified, incoming `?search=` query parameters automatically apply case-insensitive `ILIKE` clauses across the chosen columns.

<Callout type="info" title="Site-Wide Search">
  For site-wide search across multiple collections and models, see [Search &
  Discovery](/docs/dev/search).
</Callout>

## Quick start [#quick-start]

`ContentDataTable` is VitNode's reusable table UI: it renders rows, toolbar,
search, sorting, and pagination. It does not fetch data. See [Data
Table](/docs/ui/data-table) for the navigation provider it needs around it.

### Accept `search` in the route query [#accept-search-in-the-route-query]

Extend `zodPaginationQuery` to accept the optional search string:

```ts title="plugins/reactions/src/api/modules/reactions/routes/get.route.ts"
import { z } from "@hono/zod-openapi"
import { zodPaginationQuery } from "@vitnode/core/api/lib/with-pagination"

request: {
  query: zodPaginationQuery.extend({
    search: z.string().optional(), // [!code ++]
  }),
}
```

</Step>
<Step>

### Supply searchable columns [#supply-searchable-columns]

List the columns to filter in the `search` array:

```ts title="plugins/reactions/src/api/modules/reactions/routes/get.route.ts"
const data = await withPagination({
  c,
  params: { query },
  table: reactions,
  primaryCursor: reactions.id,
  // [!code ++:1]
  search: [reactions.emoji, reactions.description], // Filters across both columns
  query: async ({ cursorSelection, limit, where, orderBy }) =>
    await c
      .get('db')
      .select({ ...getColumns(reactions), ...cursorSelection })
      .from(reactions)
      .where(where)
      .orderBy(orderBy)
      .limit(limit),
})
```

</Step>
<Step>

### Show the table search input [#show-the-table-search-input]

Enable the shared table UI after its route loader returns `{ edges, pageInfo }`:

```tsx title="src/views/reactions-table.tsx"
<ContentDataTable
  id="reactions-table"
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'emoji', order: 'asc' } }}
  search // [!code ++]
  searchPlaceholder="Search reactions..." // [!code ++]
/>
```

The table automatically updates the `?search=` query parameter as the user types with debouncing.

</Step>
</Steps>

## Learn More [#learn-more]

# Debugging (/docs/dev/debugging)

Four surfaces, each answering a different question. Two of them exist only in
development - the devtools and React Scan. The other two, the AdminCP Debug
Panel and the server's own output, are how you see inside a production
deployment, which is exactly when you need to.

## Where to look first [#where-to-look-first]

| Symptom                                     | Look here                                                 |
| ------------------------------------------- | --------------------------------------------------------- |
| A request 500s in production                | [Debug Panel](#the-debug-panel) → System Logs             |
| A screen shows data that has moved on       | [Query devtools](#devtools-in-development) → find the key |
| A route loaded the wrong thing              | [Router devtools](#devtools-in-development) → loader data |
| A page feels slow to type in or scroll      | [React Scan](#react-scan) → count the re-renders          |
| A service looks configured but does nothing | **Core → System → Integrations** in the AdminCP           |
| A background job never ran                  | [Debug Panel](#the-debug-panel) → Queue Tasks             |

## The Debug Panel [#the-debug-panel]

`/admin/core/debug`, and the quickest way in is the avatar menu in the top-right
of the AdminCP: **Debug Panel**. It is also the one AdminCP screen with no
sidebar entry, so that menu (or the admin search) is how you get there.

Three sections, top to bottom:

| Section         | What it shows                                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Clear Cache** | A button, top-right. Marks every cached query stale and re-runs every matched route loader.                                                                            |
| **Queue Tasks** | Four counters - pending, processing, completed, failed - and a table of what is pending or processing right now, with its attempt count and when it is next available. |
| **System Logs** | Every line anything wrote with `c.get('log')`, newest first, sortable by type, plugin or date.                                                                         |

{/* Image prompt: A screenshot of the VitNode AdminCP Debug Panel at /admin/core/debug - heading "Debug Panel" with a "Clear Cache" button, below it a row of four queue counters (Pending, Processing, Completed, Failed), and below that the System Logs table with Plugin, Type, Status Code, Created At and Content columns, one row carrying a red "Error" badge. Dark theme, 1440x900. */}

Click any log row for the full record: the log id, the request method and path,
the status code, the IP address, the user agent, the user who caused it (linked
straight to their AdminCP profile) and the untruncated message. That detail
dialog is usually the whole debugging session.

The screen is gated on the `debug` staff module - `can_view` to open it,
`can_clear_cache` for the button - and Hono re-checks that on every request, so
hiding the menu entry is a courtesy rather than the boundary. See
[staff permissions](/docs/dev/working-with-users/staff-permissions).

<Callout
  type="warn"
  title="In production, the log is the only copy of the error"
>
  An unhandled error in a route is caught by the API's error handler, written to
  the system log as `Unhandled error: …`, and answered to the browser as the
  string `Internal Server Error` with no detail at all. In development the same
  handler returns the real message in the response body instead. So a 500 you
  cannot reproduce locally is a 500 you read in the Debug Panel.
</Callout>

## Devtools in development [#devtools-in-development]

The scaffold mounts a floating devtools button in the bottom-right corner of
every page, with two panels behind it. It comes from two places, and both are in
a generated app already:

```ts title="vite.config.ts"
import { devtools } from '@tanstack/devtools-vite'

plugins: [
  devtools(), // [!code ++]
]
```

```tsx title="src/routes/__root.tsx"
<body suppressHydrationWarning>
  {children}

{import.meta.env.DEV ? ( // [!code ++]
    <TanStackDevtools
      config={{ position: 'bottom-right' }}
      plugins={[
        { name: 'TanStack Router', render: <TanStackRouterDevtoolsPanel /> },
        { name: 'TanStack Query', render: <ReactQueryDevtoolsPanel /> },
      ]}
    />
  ) : null}

<Scripts />
</body>
```

That `import.meta.env.DEV` is why nothing ships to production: the whole block
is compiled out of a `vite build`.

| Panel               | Reach for it when                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TanStack Router** | You want the matches for the current URL, each route's loader data, and what its `head` resolved to. The answer to "why is this page rendering that". |
| **TanStack Query**  | A screen is showing stale data. Find the key, then find the mutation that should have invalidated it.                                                 |

{/* Image prompt: A screenshot of a VitNode dev server at localhost:3000 with the TanStack Devtools panel open on the TanStack Query tab - a list of cached query keys down the left, one selected, its cached JSON and a fresh/stale badge in the detail pane on the right. Dark theme, 1440x900. */}

Navigate around with the Query panel open and the shape of
[data fetching](/docs/dev/fetcher) becomes obvious: a route's loader warms
its entries before React renders, and the screen reads the same ones back.

<Callout type="info" title="Server-side requests are not in the panel">
  A loader that runs during SSR runs in the Node process, so its output lands in
  the terminal running `vite dev` - not in a browser panel. The Query panel
  shows the entry once it is dehydrated into the page.
</Callout>

## React Scan [#react-scan]

[React Scan](https://react-scan.com/) draws an outline around every component as
it re-renders, which turns "this page feels heavy" into a number. It is off by
default; flip `debug` in the [shared config](/docs/dev/configuration):

```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  debug: true, // [!code ++]
  i18n: {
    defaultLocale: 'en',
    locales: [{ code: 'en', name: 'English' }],
  },
  metadata: {
    shortTitle: 'VitNode',
    title: 'VitNode',
  },
  plugins: [],
  theme: {
    defaultTheme: 'system',
  },
})
```

The provider loads `react-scan` lazily and only when `debug` is on **and**
`NODE_ENV` is `development`, so leaving `debug: true` committed cannot leak the
overlay into production. It is still worth turning back off - the outlines are
distracting once you have your answer.

Once you have found the culprit, [Performance](/docs/dev/performance) covers
what to do about it.

## Where output goes [#where-output-goes]

| Destination           | What arrives there                                                                     |
| --------------------- | -------------------------------------------------------------------------------------- |
| The `core_logs` table | Every `c.get('log')` call, with the request that made it. Read it in the Debug Panel.  |
| The server's stdout   | The same lines, colour-coded and prefixed `[VitNode] Error (@your/plugin):`.           |
| The browser console   | Client-side errors, and React Scan's own output.                                       |
| The terminal          | Vite's dev-server output, plus anything a loader or server function logged during SSR. |

There is no request logger, and no log-level switch: every level is written
every time, to both the table and the console. If you want less noise, log less.
[Logging](/docs/dev/debugging/logging) is the whole surface.

## Gotchas [#gotchas]

<Callout
  type="warn"
  title="Every log line is a database INSERT, and nothing prunes them"
>
  `c.get('log')` writes a row per call and no cron job deletes any of them, so a
  `debug` line in a hot request path grows the table for as long as the
  installation runs. Log events, not traffic.
</Callout>

<Callout type="warn" title="Behind a proxy, every log line says the same IP">
  The IP on a log row - and the rate-limit bucket - is the address of the socket
  VitNode is talking to, because `X-Forwarded-For` is a header the caller writes
  and nobody should get to pick their own audit trail. Behind a reverse proxy
  that socket is the proxy, so every visitor looks like the same one. Put the
  per-visitor rate limit in the [proxy
  itself](/docs/dev/deployments/self-hosted), where the address is real.
</Callout>

<Callout type="info" title="Clear Cache clears the front end, not Redis">
  The button invalidates the TanStack Query cache and the router's loaders,
  which is the front end's memory of the API. The API's own [Redis-backed
  cache](/docs/dev/advanced/redis) is expired by the mutations that change the
  data, not from this screen.
</Callout>

## Next [#next]

# Logging (/docs/dev/debugging/logging)

Every VitNode request carries a logger. Call it and you get two things at once:
a row in the `core_logs` table, readable in the AdminCP
[Debug Panel](/docs/dev/debugging#the-debug-panel), and a coloured line on the
server's stdout. No setup, no adapter, no configuration.

## Quick start [#quick-start]

`c.get('log')` is available in any handler that has a Hono context - a route, a
middleware, a cron job, a queue task, an event listener:

```ts title="src/api/modules/orders/routes/refund.route.ts"
import { buildRoute } from '@vitnode/core/api/lib/route'

import { CONFIG_PLUGIN } from '@/const'

export const refundOrderRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: { method: 'post', path: '/refund' },
  handler: async (c) => {
    await c.get('log').warn('Refund requested with no matching payment') // [!code ++]

return c.json({ ok: true })
  },
})
```

Open the **Debug Panel** from the AdminCP avatar menu and the line is in
**System Logs**, with the plugin, the path, the status code and the signed-in
user already attached.

## The three levels [#the-three-levels]

There is no filtering: all three are always written, to both destinations. The
level is a label for whoever reads the log later, and it decides the badge
colour in the AdminCP and which `console` method the server uses.

```ts tab="Debug"
await c.get('log').debug('Search index rebuilt in 412ms')
```

```ts tab="Warn"
await c.get('log').warn('Storage adapter returned no public URL')
```

```ts tab="Error"
await c.get('log').error(`Payment webhook rejected: ${reason}`)
```

</Tabs>

| Level   | Console         | Use it for                                                          |
| ------- | --------------- | ------------------------------------------------------------------- |
| `debug` | `console.debug` | Something you want to see once while you work out what happened.    |
| `warn`  | `console.warn`  | A recoverable surprise - a fallback taken, a retry, a skipped step. |
| `error` | `console.error` | Something failed and somebody has to know.                          |

## What every line records [#what-every-line-records]

You pass a string. The logger reads the rest off the request, so a log row is
already an audit record:

| Column       | Where it comes from                                                                      |
| ------------ | ---------------------------------------------------------------------------------------- |
| `content`    | Your message.                                                                            |
| `type`       | The method you called.                                                                   |
| `pluginId`   | The `pluginId` the route was built with - `core` when there is no plugin on the context. |
| `method`     | The request method, upper-cased.                                                         |
| `path`       | The request path.                                                                        |
| `statusCode` | `c.res.status` **at the moment you call it** - see the gotcha below.                     |
| `ipAddress`  | The request's forwarded IP, or `127.0.0.1` when no proxy header is present.              |
| `userAgent`  | The `User-Agent` header.                                                                 |
| `userId`     | The signed-in user, or null for a guest.                                                 |
| `createdAt`  | Now.                                                                                     |

That is also why you should not build any of it into the message yourself: the
Debug Panel's detail dialog shows every column, and a message that repeats the
path just makes the table harder to scan.

## Read it back [#read-it-back]

Three ways, in descending order of convenience:

1. **The Debug Panel** at `/admin/core/debug` - sortable by type, plugin or
   date, with a detail dialog per row.
2. **The server console** - the same lines, live, prefixed
   `[VitNode] Error (@your/plugin):`.
3. **The API**, if you want to build your own view:
   `GET /api/@vitnode/core/admin/debug/logs`, cursor-paginated, `orderBy` one of
   `type`, `createdAt` or `pluginId`, gated on the `debug.can_view` staff
   permission.

## Gotchas [#gotchas]

<Callout type="warn" title="Nothing prunes core_logs">
  There is no retention policy and no cleanup job - the hourly `clean` cron
  removes expired sessions and tokens, and never touches logs. Every call is an
  `INSERT` that stays. So log events, not requests: a `debug` line in a handler
  that runs on every page view will outgrow the rest of your database.
</Callout>

<Callout type="warn" title="Await it">
  All three methods are `async` because they hit the database. A floating
  promise can lose the row if the response ends first, and an insert that fails
  becomes an unhandled rejection instead of an error you can see. `await` every
  call.
</Callout>

<Callout type="warn" title="The status code is the status so far">
  `statusCode` is read off `c.res` when you log, and a Hono response you have
  not built yet reads as `200`. A line written before `return c.json(…, 400)`
  records `200`. If the status is the interesting part, log after you know it,
  or put it in the message.
</Callout>

<Callout
  type="info"
  title="The plugin column follows the route, not the caller"
>
  It comes from the `pluginId` passed to `buildRoute`, so a plugin's cron job -
  which runs inside core's cron endpoint - is logged as `@vitnode/core`. Name
  your plugin in the message when the attribution matters.
</Callout>

<Callout type="info" title="Unhandled errors are logged for you">
  Anything a handler throws that is not an `HTTPException` is caught by the
  API's error handler, written here as `Unhandled error: …`, and answered to the
  browser as a bare `Internal Server Error` in production. You do not need a
  `try/catch` just to get a stack into the log.
</Callout>

## Next [#next]

# Vercel (/docs/dev/deployments/cloud/vercel)

A VitNode app builds with Nitro, and Nitro knows Vercel. Push the repository,
point a project at it, and the site plus the Hono API mounted at `/api/*` come
up as one serverless function - no adapter, no `vercel.json`.

Serverless is the catch, not the build. Three things VitNode can do need a
process that is still alive between requests, and Vercel does not have one - and
nothing there will run your migrations either.

## What works, and what does not [#what-works-and-what-does-not]

| Feature                                                | On Vercel      | Why                                                                         |
| ------------------------------------------------------ | -------------- | --------------------------------------------------------------------------- |
| The site, SSR, and `/api/*`                            | ✅ Works       | One Nitro function answers every route.                                     |
| Postgres, [Redis](/docs/dev/advanced/redis), email, AI | ✅ Works       | All reached over the network. Bring managed ones.                           |
| [S3 / R2](/docs/dev/storage/s3-r2) or Supabase storage | ✅ Works       | Uploads go straight to the bucket.                                          |
| [Local file storage](/docs/dev/storage/local)          | ❌ Not durable | The adapter writes to `public/uploads` on a filesystem that disappears.     |
| [WebSockets](/docs/dev/websocket)                      | ❌ Unsupported | The `/ws` upgrade needs a long-lived `serve()` with a WebSocket server.     |
| [In-process cron](/docs/dev/cron/node-cron)            | ❌ Unsupported | The adapter runs a `*/1 * * * *` timer inside the process.                  |
| Migrating on deploy                                    | ⚠️ Your job    | Nothing on Vercel runs `db:migrate` for you. See [Migrations](#migrations). |

## Deploy it [#deploy-it]

### Bring a managed Postgres [#bring-a-managed-postgres]

Anything reachable over the internet: Supabase, Neon, RDS, your own box. Create
the database and keep the connection string.

Use the **pooled** connection string if your provider offers one. VitNode
connects with `postgres.js`, which opens a pool of up to 10 connections per
process, and a serverless platform will happily run a lot of processes at once.
If you would rather keep the direct string, shrink the pool instead:

```ts title="src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  dbProvider: drizzle({
    connection: { url: POSTGRES_URL, max: 1 }, // [!code ++]
    relations: coreRelations,
  }),
})
```

Most pooled strings run in transaction mode (the Supabase pooler on port
`6543`, PgBouncer with `pool_mode = transaction`). Those need `prepare: false`
in the same object, or queries start failing with `prepared statement "..." does
not exist`. The [Connection pool](/docs/dev/database#connection-pool) section
has the details and a sizing rule.

</Step>
<Step>

### Set the environment variables first [#set-the-environment-variables-first]

In the Vercel project, before the first build - two of them are compiled into
the browser bundle and cannot be changed afterwards without building again.

| Variable                     | Notes                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `POSTGRES_URL`               | Required. Nothing works without it.                                                                     |
| `VITNODE_WEB_URL`            | Your production origin. Email links, SSO callbacks and password-reset links use it.                     |
| `CRON_SECRET`                | Required if anything schedules cron. A long random string.                                              |
| `REDIS_URL` `REDIS_PASSWORD` | Strongly recommended - see the rate-limiter gotcha below.                                               |
| `VITNODE_TRUSTED_PROXY_HOPS` | `1`. Vercel's edge is the one proxy in front of your app, so the rate limiter sees real visitor IPs.    |
| `VITNODE_API_URL`            | Leave it unset. The single app answers `/api/*` itself, and both halves work that out from the request. |

<Callout type="warn" title="Do not set VITNODE_API_URL on preview deployments">
  A preview gets a generated hostname, so no configured value can name it. Left
  unset, the server takes the API origin off the request being rendered and the
  browser falls back to the origin the page came from - which is right on every
  deployment, including ones that did not exist when you configured the project.
  Set it only when the API genuinely lives somewhere else.
</Callout>

</Step>
<Step>

### Create the project [#create-the-project]

Import the Git repository in Vercel. Three settings matter:

| Setting             | Value                                                                      |
| ------------------- | -------------------------------------------------------------------------- |
| **Root Directory**  | The app folder - `apps/web` for a monorepo, the repository root otherwise. |
| **Build Command**   | Your `build` script. For a Single App that is `vite build`.                |
| **Node.js Version** | 22 or newer.                                                               |

Leave the output directory alone. Nitro reads `VERCEL` from the build
environment, resolves its `vercel` preset without being told to, and writes
`.vercel/output` in the Build Output API format that Vercel picks up on its own.

</Step>
<Step>

### Migrate the database [#migrate-the-database]

Not from Vercel. Run it yourself, against the production connection string,
from a checkout of the commit you are deploying:

```bash tab="bun"
POSTGRES_URL="postgresql://…" bun db:migrate
```

```bash tab="pnpm"
POSTGRES_URL="postgresql://…" pnpm db:migrate
```

```bash tab="npm"
POSTGRES_URL="postgresql://…" npm run db:migrate
```

</Tabs>

See [Migrations](#migrations) for why this is not part of the build command, and
what happens if you make it one anyway.

</Step>
<Step>

### Register the first account [#register-the-first-account]

Deploy, open the site, and go to `/register`. The first account created in an
empty database becomes the **Administrator** - so do it before you tell anybody
the URL. Then sign in at `/admin` and open **Core → System → Integrations** to
see which services actually came up.

{/* Image prompt: A screenshot of the VitNode AdminCP Integrations board at /admin/core/system/integrations on a production deployment - nine service cards, Redis and Storage showing "Active" badges, WebSocket and Cron showing "Inactive". Dark theme, 1440x900. */}

</Step>
</Steps>

## Migrations [#migrations]

`start` never migrates, and on Vercel there is no `start` at all - your code is
invoked per request. So the schema has to be changed by something outside the
deployment, and there are exactly two honest ways to do it:

1. **From your own machine or CI**, pointing `POSTGRES_URL` at production, as a
   deliberate step before you promote the build. This is the one to prefer.
2. **In front of the build command** - `pnpm db:migrate && pnpm build`. It
   works, and it also runs on every preview deployment against whatever
   `POSTGRES_URL` that environment has.

<Callout type="warn" title="db:migrate can generate as well as apply">
  `db:migrate` is `vitnode migrate`, which generates a migration for any
  uncommitted schema change, then applies everything pending, then seeds. On a
  deploy there should be nothing to generate - so commit your `migrations/`
  folder, and treat a freshly generated migration on a build machine as a sign
  that something never made it into the repository.
</Callout>

## Gotchas [#gotchas]

<Callout
  type="warn"
  title="Without Redis, the rate limiter counts per instance"
>
  It falls back to in-memory storage, and on serverless "in memory" means one
  counter per cold start. The limit is still there; it just stops meaning
  anything. Set `REDIS_URL` and the counters become shared - the same switch
  also gives you a real cache.
</Callout>

<Callout type="warn" title="Vercel's own Cron Jobs cannot drive VitNode's cron">
  VitNode's endpoint is `POST /api/@vitnode/core/cron` with an `Authorization:
  Bearer $CRON_SECRET` header, and [Vercel Cron
  Jobs](https://vercel.com/docs/cron-jobs) invoke a path with a `GET`. Use a
  scheduler that can send a `POST` - GitHub Actions, an uptime service, anything
  on the [REST API](/docs/dev/cron/rest-api) page - and point it at that path
  once a minute.
</Callout>

<Callout type="warn" title="Leave cookieDomain unset">
  `authorization.cookieDomain` is empty by default, which makes every auth
  cookie host-only and therefore correct on a hostname nobody configured. Set it
  to your production domain and preview deployments stop being able to sign
  anyone in, because a browser rejects a `Domain` the response did not come
  from.
</Callout>

<Callout type="info" title="Swagger ships with the deployment">
  `/api/swagger` is mounted with no session check, so it is public on your
  production URL too. There is no proxy in front of a Vercel function to deny it
  at, so if that matters, keep the deployment behind Vercel's own access
  controls - see [Swagger](/docs/dev/swagger).
</Callout>

<Callout type="info" title="Need any of the three?">
  Run the app on a server instead. Long-lived WebSocket connections, an
  in-process scheduler and local disk are all ordinary there - see
  [Self-hosted](/docs/dev/deployments/self-hosted).
</Callout>

## Next [#next]

# Prerender Static Pages (/docs/dev/deployments/prerendering)

Prerendering renders a page once, during `vitnode build`, and saves it as an HTML file the server sends as-is. Use it for pages that look the same for every visitor - a home page, a pricing page, a list of solutions. Your server stops rendering them on every request, and visitors get the page as fast as a static file can travel.

Pages that change per visitor - settings, anything behind a sign-in, a feed of new posts - stay server-rendered. You do not need to change them.

## Prerender your pages [#prerender-your-pages]

### List the pages [#list-the-pages]

Create a module with the paths to prerender. Write each path once, without a locale prefix:

```ts title="src/prerender.ts"
export const PRERENDERED_PATHS = ['/', '/pricing', '/solutions']
```

A route with a parameter, such as `/solutions/$slug`, is never found on its own. List every value you want as a file: `/solutions/help-center`.

</Step>
<Step>

### Hand the list to Nitro [#hand-the-list-to-nitro]

Pass the paths through `prerenderRoutes` from `@vitnode/core/framework/vite` and give the result to the `prerender.routes` option of `nitro()`:

```ts title="vite.config.ts"
import { prerenderRoutes, vitnode } from '@vitnode/core/framework/vite' // [!code highlight]
import { nitro } from 'nitro/vite'
import { defineConfig } from 'vite'

import { PRERENDERED_PATHS } from './src/prerender.ts' // [!code highlight]
import { vitNodeConfig } from './src/vitnode.config.ts' // [!code highlight]

export default defineConfig({
  plugins: [
    vitnode({ appRoot: import.meta.dirname }),
    nitro({
      // [!code highlight:6]
      prerender: {
        routes: prerenderRoutes({
          i18n: vitNodeConfig.i18n,
          paths: PRERENDERED_PATHS,
        }),
      },
    }),
    // tailwindcss(), tanstackStart(), viteReact() as before
  ],
})
```

`prerenderRoutes` writes every path once per enabled locale, using the same URL rules as the router. With English as the default and Polish as a second locale, `/pricing` becomes `/pricing` and `/pl/pricing`, and a translated path from `i18n.routePaths` is used where one exists.

Vite loads this file before anything else is built, so keep the `.ts` extension on local imports and keep the path module free of components.

</Step>
<Step>

### Build [#build]

```bash tab="bun"
bun run build
```

```bash tab="pnpm"
pnpm build
```

```bash tab="npm"
npm run build
```

</Tabs>

Nitro starts a temporary server, requests every route, and writes the HTML into `.output/public` before it packages your production server.

</Step>
</Steps>

## Check the result [#check-the-result]

Each listed route has its own file, one folder per path:

```text
.output/public/index.html
.output/public/pricing/index.html
.output/public/pl/pricing/index.html
```

Start the app with `vitnode start` and compare the headers of a prerendered page and a server-rendered one:

```bash
curl -sI http://localhost:3000/pricing
curl -sI http://localhost:3000/login
```

The prerendered page answers with an `etag` and a `last-modified` date. The server-rendered page answers with `cache-control: private, no-store` instead, because VitNode renders it for one visitor - unless its route has a [page cache](/docs/dev/cache/pages) policy, which renders it once for everybody.

## What a prerendered page leaves out [#what-a-prerendered-page-leaves-out]

A prerendered file is shared by every visitor and built without your API, so VitNode leaves out anything that comes from the database or belongs to one visitor. Your build does not need a database.

- **The user menu loads in the browser.** The main layout skips reading the session while prerendering. The header ships with a placeholder where the avatar goes, and the browser fills it in once the page loads - the same thing a server-rendered page shows for a split second.
- **The header navigation loads in the browser.** The links you edit in **AdminCP → System → Navigation** are not part of the file. The header shows a placeholder in their place, the browser asks the API for the links once the page loads, and a change shows up right away, without a rebuild.
- **The language choice is stored by the browser.** A visit to `/pl/...` normally sets the locale cookie in the server's response. A static file has no such response, so VitNode sets the same cookie from the browser when the page loads.

## Pages you should not prerender [#pages-you-should-not-prerender]

<Callout type="warn" title="Per-domain locales cannot be prerendered">
  With `i18n.domains`, one path serves a different language on every domain, and
  one file cannot do that. `prerenderRoutes` throws a `PrerenderDomainsError`
  instead of writing the wrong language. Keep those pages server-rendered.
</Callout>

Only list pages that look the same for everyone. A page behind a sign-in would be prerendered as a signed-out visitor sees it, and every signed-in visitor would get that copy.

A page whose own loader reads from your API - a list of the latest blog posts, for example - needs that API and its database during the build, and its content stays as it was at build time. Keep such pages server-rendered too.

# Self-Hosted Deployment (/docs/dev/deployments/self-hosted)

VitNode compiles into a standard Node.js server and static assets. The only required dependency is a PostgreSQL database (Redis is optional for caching and multi-instance scaling).

## Quick start [#quick-start]

Run these 4 commands on your deployment server:

```bash tab="bun"
bun install --frozen-lockfile
bun run build
bun run db:migrate
bun start
```

```bash tab="pnpm"
pnpm install --frozen-lockfile
pnpm build
pnpm db:migrate
pnpm start
```

```bash tab="npm"
npm ci
npm run build
npm run db:migrate
npm start
```

</Tabs>

<Callout type="warn" title="Always run db:migrate before start">
  Production processes do not automatically run migrations at boot. Running
  `db:migrate` ensures the database schema matches your compiled application
  before traffic is served.
</Callout>

---

## Required Environment Variables [#required-environment-variables]

Configure these in your production `.env` file:

```bash title=".env"
# Database (PostgreSQL 15+)
POSTGRES_URL=postgresql://user:password@localhost:5432/vitnode_db

# The origin visitors reach. Email links, SSO callbacks and password-reset
# links are built from it.
VITNODE_WEB_URL=https://example.com

# Required if anything schedules cron. A long random string.
CRON_SECRET=change_me_to_a_long_random_secret_string

# How many proxies sit in front of the app: 1 behind the Nginx config below,
# 0 when the app is exposed directly. See the rate limiter docs.
VITNODE_TRUSTED_PROXY_HOPS=1

# Optional: Shared Cache & Realtime
REDIS_URL=redis://localhost:6379
REDIS_PASSWORD=change_me_redis_password
```

### Where the API lives [#where-the-api-lives]

A **Single App** answers `/api/*` itself, so leave `VITNODE_API_URL` unset.
The server takes the API origin off the request being rendered and the browser
falls back to the origin the page was served from, so the same build is correct
on every hostname you point at it.

A **split deployment** runs the web app and `apps/api` as two processes, and the
web app then has to be told where the API is - its own origin has no `/api/*` to
answer, so an unset value turns every server-side call into a 404, starting with
the session read on the first render. Set it in the web app's environment, and
set it before the build: it is compiled into the browser bundle too.

```bash title="apps/web/.env"
VITNODE_API_URL=http://localhost:8000
```

A value set here wins over the request origin, which is why a Single App must
not carry one - `http://localhost:3000` left over from development would point
production at the visitor's own machine.

---

## Reverse Proxy (Nginx Configuration) [#reverse-proxy-nginx-configuration]

Proxy traffic to VitNode while forwarding client headers and supporting WebSocket upgrades:

```nginx title="/etc/nginx/sites-available/vitnode.conf"
server {
    listen 80;
    server_name example.com;

location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;

# WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

# Forwarded identity
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

Keep `proxy_set_header Host $host;`. VitNode picks a [language domain](/docs/dev/i18n/localized-urls#behind-a-proxy) from the `Host` header and deliberately ignores `X-Forwarded-Host`, which any visitor can send.

---

## Running with PM2 (Process Manager) [#running-with-pm2-process-manager]

Keep VitNode running continuously with automatic restarts on crash:

```bash tab="bun"
# Install PM2
bun add -g pm2

# Start both web and API processes
pm2 start "bun start" --name "vitnode-web"
pm2 save
pm2 startup
```

```bash tab="pnpm"
# Install PM2
pnpm add -g pm2

# Start both web and API processes
pm2 start "pnpm start" --name "vitnode-web"
pm2 save
pm2 startup
```

```bash tab="npm"
# Install PM2
npm install -g pm2

# Start both web and API processes
pm2 start "npm start" --name "vitnode-web"
pm2 save
pm2 startup
```

</Tabs>

## Learn More [#learn-more]

# Button (/docs/dev/email/components/button)

`EmailButton` wraps React Email's `Button` with the variants the app's own
button uses, so a call to action in a mail looks like a call to action on the
site. It renders an `<a>`, which is the only thing every mail client agrees to
style.

## Preview [#preview]

## Usage [#usage]

```ts
import { EmailButton } from '@vitnode/core/emails/ui/button'
```

```tsx
<EmailButton href="https://vitnode.com/">Default</EmailButton>
```

Centre it the way the framework's own password-reset mail does - a `Section`
does the alignment, because margins are not to be trusted in email:

```tsx
<Section className="text-center">
  <EmailButton className="min-w-[200px]" href={resetUrl} size="lg">
    Reset your password
  </EmailButton>
</Section>
```

## Props [#props]

Everything an `<a>` takes, plus two of its own.

### Variants [#variants]

| Variant            | Looks like                     | Use it for                                 |
| ------------------ | ------------------------------ | ------------------------------------------ |
| `default`          | Solid primary fill, light text | The one action the email is asking for     |
| `secondary`        | Soft tinted fill, dark text    | A second, lesser action                    |
| `outline`          | Border, page-background fill   | A neutral action next to a primary one     |
| `ghost`            | Text only, no fill or border   | Tertiary actions                           |
| `link`             | Primary-coloured text, no fill | Inline links styled as buttons             |
| `destructive`      | Solid red fill, white text     | Delete, revoke, cancel                     |
| `destructiveGhost` | Red text, no fill              | A destructive action that should not shout |

### Sizes [#sizes]

| Size      | Padding       |
| --------- | ------------- |
| `sm`      | `px-3 py-1.5` |
| `default` | `px-4 py-2`   |
| `lg`      | `px-6 py-2.5` |

## Gotchas [#gotchas]

<Callout type="warn" title="The colours come from the template">
  `bg-primary` and friends are defined by `DefaultTemplateEmail`, which wraps
  your content in a `<Tailwind>` with VitNode's palette. Drop an `EmailButton`
  into a template that builds its own document and the classes resolve to
  nothing. [Templates](/docs/dev/email/templates#colour-tokens) lists the
  tokens.
</Callout>

<Callout type="info" title="It is a link, not a button">
  There is no `onClick` and no `type="submit"` to reach for - email has no
  JavaScript. Every action is a URL, which usually means a signed link into your
  app.
</Callout>

## Next [#next]

# Card (/docs/dev/email/components/card)

`EmailCard` is the container the framework's own mail puts its message in: a
white panel with a border, a rounded corner and consistent padding. Six
components, each a thin wrapper over a React Email primitive, so they compose
like the app's card does.

## Preview [#preview]

## Usage [#usage]

```ts
import {
  EmailCard,
  EmailCardContent,
  EmailCardDescription,
  EmailCardFooter,
  EmailCardHeader,
  EmailCardTitle,
} from '@vitnode/core/emails/ui/card'
import { Text } from 'react-email'
```

```tsx
<EmailCard>
  <EmailCardHeader>
    <EmailCardTitle>Card Title</EmailCardTitle>
    <EmailCardDescription>Card Description</EmailCardDescription>
  </EmailCardHeader>
  <EmailCardContent>
    <Text className="m-0">
      This is the content of the card. You can put any content here.
    </Text>
  </EmailCardContent>
  <EmailCardFooter>
    <Text className="m-0">Footer</Text>
  </EmailCardFooter>
</EmailCard>
```

Every part is optional. A card with nothing but `EmailCardContent` inside it is
a perfectly good panel.

## Components [#components]

| Component              | Renders                 | Styling it brings                                       |
| ---------------------- | ----------------------- | ------------------------------------------------------- |
| `EmailCard`            | `Section` (a `<table>`) | Card background, border, `rounded-xl`, vertical padding |
| `EmailCardHeader`      | `Section`               | Horizontal padding and space below                      |
| `EmailCardTitle`       | `Text` (a `<p>`)        | `text-xl font-semibold`, with the line height zeroed    |
| `EmailCardDescription` | `Text`                  | Muted, small, no margin                                 |
| `EmailCardContent`     | `Section`               | Horizontal padding                                      |
| `EmailCardFooter`      | `Section`               | Horizontal padding and space above                      |

## Props [#props]

Each component takes the props of the primitive it renders - so `className`,
`style` and children, plus the table or paragraph attributes underneath.

## Gotchas [#gotchas]

<Callout type="warn" title="The colours come from the template">
  `bg-card`, `border-border` and `text-muted-foreground` are defined by
  `DefaultTemplateEmail`, which wraps your content in a `<Tailwind>` carrying
  VitNode's palette. In a template that builds its own document, those classes
  resolve to nothing. [Templates](/docs/dev/email/templates#colour-tokens) lists
  the tokens.
</Callout>

<Callout type="info" title="Reset the paragraph margins">
  A React Email `Text` renders a `<p>` with its own margins, which stack oddly
  inside a padded section. That is why the snippets above pass `m-0` on the
  paragraphs they place directly in a card.
</Callout>

<Callout type="info" title="Sections are tables">
  Each of these renders a `<table>`, because that is what survives Outlook.
  Nesting them is fine and expected; floating or absolutely positioning them is
  not a thing email can do.
</Callout>

## Next [#next]

# Custom Email Adapter (/docs/dev/email/custom-adapter)

You can connect any transactional email service (e.g. Postmark, AWS SES, SendGrid, Mailgun) by implementing the `EmailApiPlugin` interface. VitNode handles template rendering, i18n localization, and recipient resolution; your adapter just sends the email.

## The `EmailApiPlugin` Interface [#the-emailapiplugin-interface]

The adapter contract consists of a single `sendEmail` method:

```ts
export interface EmailApiPlugin {
  sendEmail: (args: {
    to: string
    subject: string
    html: string
    text: string
    metadata: { title: string; shortTitle?: string }
    replyTo?: string
    idempotencyKey?: string
  }) => Promise<EmailSendResult | void>
}

export interface EmailSendResult {
  id?: string // the provider's message id
}
```

---

## Quick start: Implementing an Adapter [#quick-start-implementing-an-adapter]

### 1. Create the Adapter Factory [#1-create-the-adapter-factory]

```ts title="apps/api/src/lib/email/postmark-adapter.ts"
import type { EmailApiPlugin } from "@vitnode/core/api/models/email"

export const PostmarkEmailAdapter = ({
  serverToken,
  from,
}: {
  serverToken: string
  from: string
}): EmailApiPlugin => ({
  // [!code ++:16]
  sendEmail: async ({ to, subject, html, text, metadata }) => {
    const res = await fetch("https://api.postmarkapp.com/email", {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
        "X-Postmark-Server-Token": serverToken,
      },
      body: JSON.stringify({
        From: `${metadata.shortTitle ?? metadata.title} <${from}>`,
        To: to,
        Subject: subject,
        HtmlBody: html,
        TextBody: text,
      }),
    })

if (!res.ok) throw new Error(`Postmark error: ${res.statusText}`)
  },
})
```

---

### 2. Register in API Configuration [#2-register-in-api-configuration]

Attach the adapter to `vitNodeApiConfig` in `apps/api/src/vitnode.api.config.ts`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"
import { PostmarkEmailAdapter } from "./lib/email/postmark-adapter"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:7]
  email: {
    adapter: PostmarkEmailAdapter({
      serverToken: process.env.POSTMARK_SERVER_TOKEN!,
      from: "notifications@yourdomain.com",
    }),
  },
})
```

---

## `sendEmail` Arguments [#sendemail-arguments]

## Idempotency and the Return Value [#idempotency-and-the-return-value]

Callers such as [notification emails](/docs/dev/notifications/email-and-digests) retry a send that failed or never got an answer, with the same `idempotencyKey`. Forward it to a provider that deduplicates on a key, and a retry after an accepted-but-unconfirmed send is dropped instead of delivered twice. Resend does this; SMTP cannot, so Nodemailer ignores the key.

Return `{ id }` with the provider's message id when you have one - it shows up in the AdminCP delivery list. Returning nothing is still valid.

```ts
sendEmail: async ({ to, subject, html, text, metadata, idempotencyKey }) => {
  const res = await fetch("https://api.postmarkapp.com/email", {
    /* ...as above, plus your provider's idempotency field if it has one */
  })
  if (!res.ok) throw new Error(`Postmark error: ${res.statusText}`)

const { MessageID } = (await res.json()) as { MessageID: string }
  return { id: MessageID } // [!code ++]
},
```

## Learn More [#learn-more]

# Email (/docs/dev/email)

VitNode provides a unified transactional email service accessible via `c.get("email")`. Emails are rendered using React components, localized to the recipient's language, and delivered through your chosen provider.

## Quick start [#quick-start]

### Queue an email from a Hono route [#queue-an-email-from-a-hono-route]

```ts title="plugins/blog/src/api/modules/newsletter/routes/welcome.route.ts"
import { buildRoute } from '@vitnode/core/api/lib/route'

export const sendWelcomeRoute = buildRoute({
  pluginId: 'blog',
  route: {
    method: 'post',
    path: '/welcome',
    responses: { 200: { description: 'Email sent' } },
  },
  handler: async (c) => {
    const user = c.get('user')

// [!code ++:5]
    await c.get('email').send({
      user, // Resolves email address and preferred locale
      subject: 'Welcome to VitNode!',
      content: () => 'Thank you for joining our community.',
    })

return c.json({ sent: true })
  },
})
```

`send()` renders the template and queues delivery. It keeps a successful API
response quick even when the mail provider is having a moody afternoon.

</Step>
</Steps>

<Callout type="info" title="`build()` and `deliver()` do exist">
  Use `await c.get('email').build(args)` followed by `deliver(email)` only when
  a route truly needs immediate delivery. `send(args)` is the normal, queued
  path.
</Callout>

`deliver()` takes an optional `idempotencyKey` and returns what the provider
reported, such as its message id:

```ts
const email = await c.get('email').build(args)
const { id } = await c.get('email').deliver(email, {
  idempotencyKey: `order-receipt:${order.id}`, // same key on every retry
})
```

Adapters whose provider deduplicates on a key, like Resend, forward it - so a
retry after an unconfirmed send is not delivered twice. SMTP has no such
feature and ignores it. [Notification emails](/docs/dev/notifications/email-and-digests)
use this for every send.

## Configuring Email Adapters [#configuring-email-adapters]

Configure your delivery transport in `apps/api/src/vitnode.api.config.ts`:

### 1. Resend Adapter [#1-resend-adapter]

```ts title="apps/api/src/vitnode.api.config.ts"
import { ResendEmailAdapter } from '@vitnode/core/api/adapters/email/resend'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    from: 'noreply@yourdomain.com',
    adapter: ResendEmailAdapter({
      apiKey: process.env.RESEND_API_KEY!,
    }),
  },
})
```

### 2. SMTP Adapter [#2-smtp-adapter]

```ts title="apps/api/src/vitnode.api.config.ts"
import { SmtpEmailAdapter } from '@vitnode/core/api/adapters/email/smtp'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    from: 'noreply@yourdomain.com',
    adapter: SmtpEmailAdapter({
      host: process.env.SMTP_HOST!,
      port: Number(process.env.SMTP_PORT ?? 587),
      user: process.env.SMTP_USER!,
      password: process.env.SMTP_PASSWORD!,
    }),
  },
})
```

---

## Testing Email in AdminCP [#testing-email-in-admincp]

{/* Image prompt: VitNode AdminCP System -> Integrations screen at /admin/core/system/integrations. Email card showing status "Configured" with a "Send Test Email" modal containing recipient address input and delivery confirmation toast. Dark theme, 1440x900. */}

Verify email configuration in the AdminCP at **System → Integrations** (`/admin/core/system/integrations`):

- Click **Test Email** on the email card.
- Enter an email address to dispatch an immediate test delivery.

## Learn More [#learn-more]

# Nodemailer (SMTP) (/docs/dev/email/nodemailer)

The Nodemailer adapter speaks plain SMTP, so it works with anything that has a
host, a port and a login: your own Postfix, a provider's relay, or a mail
catcher running on your laptop.

| Cloud                | Self-Hosted  | Links                                                                                                         |
| -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
| ⚠️ Runtime-dependent | ✅ Supported | [NPM Package](https://www.npmjs.com/package/@vitnode/nodemailer) · [Nodemailer docs](https://nodemailer.com/) |

SMTP needs an outbound TCP connection, which edge runtimes cannot open and many
serverless platforms block on the usual mail ports. If that is where you deploy,
use [Resend](/docs/dev/email/resend) instead.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { NodemailerEmailAdapter } from '@vitnode/nodemailer'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    adapter: NodemailerEmailAdapter({
      from: process.env.NODE_MAILER_FROM,
      host: process.env.NODE_MAILER_HOST,
      user: process.env.NODE_MAILER_USER,
      password: process.env.NODE_MAILER_PASSWORD,
    }),
  },
})
```

`port` defaults to `587` and `secure` to `false`, which is the STARTTLS
combination almost every relay wants.

## Setup [#setup]

### Install the adapter [#install-the-adapter]

`nodemailer` itself ships as a dependency of the adapter.

```bash tab="bun"
bun i @vitnode/nodemailer
```

```bash tab="pnpm"
pnpm i @vitnode/nodemailer
```

```bash tab="npm"
npm i @vitnode/nodemailer
```

</Tabs>

</Step>
<Step>

### Get an SMTP server to talk to [#get-an-smtp-server-to-talk-to]

In development, catch the mail locally instead of posting it to strangers.
[Mailpit](https://mailpit.axllent.org/) is one binary: an SMTP server on `1025`
and a web inbox on `8025`.

```bash title="Catch mail locally"
docker run -p 8025:8025 -p 1025:1025 \
  -e MP_SMTP_AUTH_ACCEPT_ANY=1 \
  -e MP_SMTP_AUTH_ALLOW_INSECURE=1 \
  axllent/mailpit
```

Both flags matter: the adapter always authenticates, and it does so over an
unencrypted local connection, which Mailpit refuses by default.

In production, take the four values from your provider's SMTP page - it is
usually called "SMTP relay", "Sending" or "Integration".

{/* Image prompt: A screenshot of a transactional email provider's SMTP credentials page, showing the server host, port 587, username and a masked password, with a copy button beside each field. Neutral light theme, 1440x900. */}

</Step>
<Step>

### Register the adapter [#register-the-adapter]

The adapter reads options, not the environment, so a port other than `587` has
to be passed through as well:

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { NodemailerEmailAdapter } from '@vitnode/nodemailer' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:10]
  email: {
    adapter: NodemailerEmailAdapter({
      from: process.env.NODE_MAILER_FROM,
      host: process.env.NODE_MAILER_HOST,
      user: process.env.NODE_MAILER_USER,
      password: process.env.NODE_MAILER_PASSWORD,
      port: Number(process.env.NODE_MAILER_PORT ?? 587),
      secure: process.env.NODE_MAILER_PORT === '465',
    }),
  },
  metadata: {
    title: 'My Community',
    shortTitle: 'Community',
  },
})
```

Recipients see `Community <hello@example.com>`: the display name is
`metadata.shortTitle ?? metadata.title`, and `from` supplies only the address.

</Step>
<Step>

### Set the environment variables [#set-the-environment-variables]

Mailpit accepts any credentials, so locally the username and password only have
to be non-empty:

```bash title=".env"
NODE_MAILER_HOST=localhost
NODE_MAILER_PORT=1025
NODE_MAILER_USER=dev
NODE_MAILER_PASSWORD=dev
NODE_MAILER_FROM=hello@localhost
```

Production is the same five lines with your provider's values and, on most
relays, `NODE_MAILER_PORT=587`.

</Step>
<Step>

### Send a test mail [#send-a-test-mail]

Send one from a route - the [email overview](/docs/dev/email#quick-start) has the
`build()` plus `deliver()` form that works from any plugin - then open
[localhost:8025](http://localhost:8025). The message appears in Mailpit's inbox,
where you can read the rendered HTML and the raw source that left your app.

{/* Image prompt: A screenshot of the Mailpit web inbox at localhost:8025 with one captured message selected, showing the rendered HTML email in the reading pane and the HTML/Text/Raw tabs above it. Light theme, 1440x900. */}

Nothing there? `deliver()` throws inside the request, so the failing request is
where Nodemailer's own message is - in the response body while `NODE_ENV` is
`development`, in the log otherwise. Mail sent with the queued `send()` is a
tick behind instead, and its story is in the row:

```sql
select status, attempts, "lastError"
from core_queue
where name = 'send-email'
order by id desc
limit 1;
```

</Step>
</Steps>

## Options [#options]

## Environment variables [#environment-variables]

The adapter takes values, not variable names, so these are yours to rename -
just keep both sides in step.

| Variable               | Maps to    | Example         | Notes                                                            |
| ---------------------- | ---------- | --------------- | ---------------------------------------------------------------- |
| `NODE_MAILER_HOST`     | `host`     | `smtp.host.com` | Required                                                         |
| `NODE_MAILER_USER`     | `user`     | `apikey`        | Required. Some providers use a fixed literal here                |
| `NODE_MAILER_PASSWORD` | `password` | -               | Required                                                         |
| `NODE_MAILER_FROM`     | `from`     | `hi@you.com`    | Required. Address only                                           |
| `NODE_MAILER_PORT`     | `port`     | `587`           | Optional - pass it through yourself, the adapter defaults to 587 |

## Gotchas [#gotchas]

<Callout type="warn" title="Missing settings fail at delivery, not at boot">
  The adapter checks `host`, `user`, `password` and `from` inside `sendEmail`,
  so a half-configured app still starts. With `deliver()` the failure is the
  route's own 500, throwing `Missing nodemailer configuration`. With the queued
  `send()` the request returns 200 and the same message turns up in
  `core_queue.lastError` three attempts later.
</Callout>

<Callout type="warn" title="Port 465 needs secure: true">
  Port 465 expects TLS immediately, while 587 negotiates it with STARTTLS.
  Leaving `secure` at its default on 465 gives you a connection that hangs and
  then times out rather than a clear error.
</Callout>

<Callout type="info" title="One connection per email">
  The transport is created inside `sendEmail`, so each message opens its own
  SMTP connection - simple and stateless, and fine at the volumes a queue
  drained once a minute produces. A relay that rate-limits connections rather
  than messages is the case to watch.
</Callout>

<Callout type="info" title="Only the HTML part is sent">
  VitNode renders both an HTML and a plain-text version of every email, but this
  adapter passes `html` alone.
</Callout>

## Next [#next]

# Resend (/docs/dev/email/resend)

[Resend](https://resend.com/) sends mail over an ordinary HTTPS request, which
makes it the adapter that works everywhere your app can `fetch` - including
serverless and edge deployments where an SMTP connection would never open.

| Cloud        | Self-Hosted  | Links                                                                                                 |
| ------------ | ------------ | ----------------------------------------------------------------------------------------------------- |
| ✅ Supported | ✅ Supported | [NPM Package](https://www.npmjs.com/package/@vitnode/resend) · [Resend docs](https://resend.com/docs) |

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { ResendEmailAdapter } from '@vitnode/resend'

export const vitNodeApiConfig = buildApiConfig({
  email: {
    adapter: ResendEmailAdapter({
      apiKey: process.env.RESEND_API_KEY,
      from: process.env.RESEND_FROM_EMAIL,
    }),
  },
})
```

That is the whole integration. The steps below are the account setup around it.

## Setup [#setup]

### Install the adapter [#install-the-adapter]

The `resend` SDK ships as a dependency of the adapter, so this is the only
package you add.

```bash tab="bun"
bun i @vitnode/resend
```

```bash tab="pnpm"
pnpm i @vitnode/resend
```

```bash tab="npm"
npm i @vitnode/resend
```

</Tabs>

</Step>
<Step>

### Create an API key [#create-an-api-key]

In the Resend dashboard, open **API Keys** and create one with send permission.
The value starts with `re_` and is shown exactly once, so copy it now.

{/* Image prompt: A screenshot of the Resend dashboard API Keys page with the "Create API Key" dialog open - name field filled in, permission set to sending access, the generated re_ key partially masked. Dark theme, 1440x900. */}

</Step>
<Step>

### Verify a sending domain [#verify-a-sending-domain]

Resend only delivers from a domain you own. Add yours under **Domains**, copy
the DKIM and SPF records it gives you into your DNS, and wait for the status to
go green.

For a first local test you can skip this and send from
`onboarding@resend.dev`, which Resend allows for testing only - it will not
carry your production mail.

{/* Image prompt: A screenshot of the Resend dashboard Domains page showing one domain with a green "Verified" status and its DKIM/SPF DNS records listed below. Dark theme, 1440x900. */}

</Step>
<Step>

### Register the adapter [#register-the-adapter]

Add the `email` block to your API config. Both values come from the
environment, so nothing secret lives in the repository:

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'
import { ResendEmailAdapter } from '@vitnode/resend' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:6]
  email: {
    adapter: ResendEmailAdapter({
      apiKey: process.env.RESEND_API_KEY,
      from: process.env.RESEND_FROM_EMAIL,
    }),
  },
  metadata: {
    title: 'My Community',
    shortTitle: 'Community',
  },
})
```

Recipients see `Community <hello@example.com>`: the display name is
`metadata.shortTitle ?? metadata.title`, and `from` supplies only the address.

</Step>
<Step>

### Set the environment variables [#set-the-environment-variables]

```bash title=".env"
RESEND_API_KEY=re_your_api_key
RESEND_FROM_EMAIL=hello@your-verified-domain.com
```

</Step>
<Step>

### Send a test mail [#send-a-test-mail]

Send one from a route - the [email overview](/docs/dev/email#quick-start) has the
`build()` plus `deliver()` form that works from any plugin. Because `deliver()`
runs inside the request, a rejection fails that request: the adapter rethrows
Resend's error as `[error_name]: message`, which is the response body in
development and a log line in production.

An accepted message appears under **Emails** in the dashboard within seconds,
with its delivery events.

Mail sent with the queued `send()` - core's password resets, for instance - is
one tick behind, and the row tells you where it got to:

```sql
select status, attempts, "lastError"
from core_queue
where name = 'send-email'
order by id desc
limit 1;
```

</Step>
</Steps>

## Options [#options]

## Environment variables [#environment-variables]

Both are read in `src/vitnode.api.config.ts`, so the names are yours to choose;
these are the ones this documentation uses.

| Variable            | Maps to  | Example                 | Notes                                                                      |
| ------------------- | -------- | ----------------------- | -------------------------------------------------------------------------- |
| `RESEND_API_KEY`    | `apiKey` | `re_123...`             | Created under **API Keys**. Needs sending permission                       |
| `RESEND_FROM_EMAIL` | `from`   | `hello@your-domain.com` | Must sit on a verified domain, or be `onboarding@resend.dev` while testing |

## Gotchas [#gotchas]

<Callout type="warn" title="Missing keys fail at delivery, not at boot">
  The adapter validates its own config inside `sendEmail`, so an unset
  `RESEND_API_KEY` never stops the API from starting. With `deliver()` the
  failure is the route's own 500, throwing `Missing Resend configuration`. With
  the queued `send()` the request still returns 200 and the same message turns
  up in `core_queue.lastError` three attempts later.
</Callout>

<Callout type="warn" title="An unverified From fails at delivery">
  Resend answers with an error rather than holding the mail, and the adapter
  rethrows it as `[error_name]: message`. If sends start failing the moment you
  switch from `onboarding@resend.dev` to your own domain, check the domain
  status before you check your code.
</Callout>

<Callout type="info" title="Only the HTML part is sent">
  VitNode renders both an HTML and a plain-text version of every email, but this
  adapter passes `html` alone - the `text` argument reaches it and goes unused.
</Callout>

## Next [#next]

# Email Templates (/docs/dev/email/templates)

VitNode renders email templates using [React Email](https://react.email). Templates are standard React components transformed into cross-client compatible HTML tables with localized text and inline styles.

## Quick start [#quick-start]

### 1. Build the Template Component [#1-build-the-template-component]

Wrap template content inside `DefaultTemplateEmail`:

```tsx title="plugins/blog/src/emails/welcome-email.tsx"
import DefaultTemplateEmail, {
  type DefaultTemplateEmailProps,
} from "@vitnode/core/emails/default-template"
import { Button, Section, Text } from "react-email"

interface WelcomeEmailProps extends DefaultTemplateEmailProps {
  loginUrl?: string
}

export default function WelcomeEmail({
  user,
  loginUrl = "https://example.com/login",
  ...props
}: WelcomeEmailProps) {
  return (
    // [!code ++:13]
    <DefaultTemplateEmail user={user} {...props}>
      <Section className="p-4 text-center">
        <Text className="text-xl font-bold">Welcome, {user.name}!</Text>
        <Text className="text-muted-foreground">
          We are thrilled to have you in the community.
        </Text>
        <Button href={loginUrl} className="bg-primary text-primary-foreground px-4 py-2 rounded-md">
          Visit Your Account
        </Button>
      </Section>
    </DefaultTemplateEmail>
  )
}
```

---

### 2. Send the Email [#2-send-the-email]

Send or queue the email from any Hono route or task:

```ts
import WelcomeEmail from "@/emails/welcome-email"

// [!code ++:6]
await c.get("email").send({
  user: { email: user.email, name: user.name },
  subject: "Welcome to VitNode!",
  content: WelcomeEmail,
})
```

`send()` handles locale resolution, renders the JSX to HTML, and pushes the delivery to the mail transport.

---

## Preview Templates Locally [#preview-templates-locally]

Preview emails in your browser during development using the React Email preview server:

```bash tab="bun"
bun run email dev
```

```bash tab="pnpm"
pnpm exec email dev
```

```bash tab="npm"
npx email dev
```

</Tabs>

Visit `http://localhost:3001` to view your email rendered live with hot reloading.

---

## Localization in Emails [#localization-in-emails]

Email templates receive the recipient's preferred locale automatically:

```tsx
export default function OrderEmail({ i18n, ...props }: DefaultTemplateEmailProps) {
  return (
    <DefaultTemplateEmail i18n={i18n} {...props}>
      <Text>{i18n.t("order.confirmed")}</Text>
    </DefaultTemplateEmail>
  )
}
```

## Learn More [#learn-more]

# Built-in Events (/docs/dev/events/built-in-events)

Every event VitNode and its first-party plugins emit today, grouped by domain.
Listen to any of them from your own plugin with
[`buildEventListener`](/docs/dev/events) - no import from the emitting plugin is
needed, because the event map is global.

## Quick start [#quick-start]

Pick a name from the tables below, write a listener for it, and register the
listener on a top-level module's `events` array:

```ts title="plugins/shop/src/api/lib/events.ts"
import { buildEventListener } from '@vitnode/core/api/lib/events'

export const welcomeListener = buildEventListener({
  event: 'user.created', // [!code ++]
  name: 'send-welcome-email',
  handler: async (c, payload) => {
    await c.get('queue').dispatch({
      name: 'send-welcome-email',
      payload: { userId: payload.userId, email: payload.email },
    })
  },
})
```

Nothing else has to change: the payload type comes from the name, and the
[delivery guarantees](/docs/dev/events#delivery-guarantees) are the same for a
core event as for one of your own.

## Core events (`@vitnode/core`) [#core-events-vitnodecore]

Seventeen names, all declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts`. Every one of them fires **after**
the write it describes has committed.

| Event                          | Payload                                   | Fires when                                                                                                               |
| ------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `user.created`                 | `{ userId, email, name, emailVerified }`  | A user row is inserted - public sign-up, AdminCP creation, or SSO sign-up                                                |
| `user.updated`                 | `{ userId, email, name }`                 | A user is edited in the AdminCP, or a member saves their own profile or time zone in **Settings → Overview**             |
| `user.deleted`                 | `{ userId, email }`                       | Never - the name is declared for plugins, core has no deletion flow                                                      |
| `user.email.verified`          | `{ userId, email }`                       | An address is [confirmed](/docs/dev/working-with-users/email-verification) - by its link, a completed reset, or by staff  |
| `user.password.updated`        | `{ userId }`                              | A password is set - by a member completing a reset, or by staff on the AdminCP user page                                 |
| `user.sessions.revoked`        | `{ userId, deviceId, sessions }`          | A user is signed out remotely - one device or all of them, by the member or by staff, or after a password change         |
| `user.sso.linked`              | `{ userId, email, providerId }`           | An SSO identity is linked to an existing account - at login with its password, or from **Settings → Connected accounts** |
| `user.sso.unlinked`            | `{ userId, providerId }`                  | A provider is disconnected - by the member in **Settings → Connected accounts**, or by staff in the AdminCP              |
| `user.sso.preferences_updated` | `{ userId, sources, sync }`               | Profile-field sources or sync-on-sign-in settings are saved - by the member or by staff                                  |
| `user.sso.profile_synced`      | `{ userId, providerId, fields, trigger }` | Profile fields were copied from a provider - by **Sync now**, **Import** or an opted-in sign-in                          |
| `user.passkey.created`         | `{ userId, passkeyId }`                   | A member adds a [passkey](/docs/dev/passkeys) in **Settings → Security**                                                 |
| `user.passkey.updated`         | `{ userId, passkeyId, name }`             | A passkey is renamed - by its owner or by staff                                                                          |
| `user.passkey.deleted`         | `{ userId, passkeyId }`                   | A passkey is removed - by its owner or by staff                                                                          |
| `user.avatar.updated`          | `{ userId, fileId }`                      | An avatar is uploaded or removed - by the user on their profile, or by staff in the AdminCP                              |
| `user.cover.updated`           | `{ userId, fileId }`                      | A profile cover is uploaded or removed - by the user on their profile, or by staff in the AdminCP                        |
| `role.created`                 | `{ roleId }`                              | A role is created in the AdminCP                                                                                         |
| `role.updated`                 | `{ roleId }`                              | A role is edited in the AdminCP                                                                                          |
| `role.deleted`                 | `{ roleId }`                              | A role is deleted in the AdminCP                                                                                         |

Emitted from `UserModel.signUp`, which is the one insert path into
`core_users` - so it covers the public sign-up form, user creation in the
AdminCP, and the first sign-in through an [SSO provider](/docs/dev/sso).

**A listener would** send a welcome or verification email (via a
[queue task](/docs/dev/advanced/queue) so it retries), subscribe the address to
a newsletter audience, or provision plugin-owned data such as a profile row.

```ts title="Example: welcome email listener"
export const welcomeListener = buildEventListener({
  event: 'user.created',
  name: 'send-welcome-email',
  handler: async (c, payload) => {
    await c.get('queue').dispatch({
      name: 'send-welcome-email',
      payload: { userId: payload.userId, email: payload.email },
    })
  },
})
```

</Accordion>
<Accordion title="user.updated">

Emitted by the AdminCP user `PATCH` after it commits - profile fields (email,
name, name code) and/or role assignments - and when a member saves their own
profile fields or time zone. The payload carries the user's **current** values.

**A listener would** sync the identity into an external system (CRM, mailing
list), invalidate a plugin-owned cache keyed by user, or audit-log the staff
edit using the envelope's `actor`.

</Accordion>
<Accordion title="user.avatar.updated">

Emitted after an avatar is stored and attached to the user, or after it is
removed. The same event covers the profile page and the AdminCP - the envelope's
`actor` tells the two apart.

**A listener would** push the new picture to a chat integration, regenerate a
cached feed card, or audit-log a staff change with the envelope's `actor`.

</Accordion>
<Accordion title="user.cover.updated">

The cover image's twin of `user.avatar.updated`, with the same payload and the
same two triggers.

</Accordion>
<Accordion title="user.sso.linked">

Emitted after the `core_users_sso` row is committed, from two places:

- `SSOModel.link` - a social identity that arrived with an already-registered
  email is tied to that account once its password checks out;
- `SsoConnectionModel.callback` - a signed-in member connects a provider from
  [Connected accounts](/docs/dev/sso/connected-accounts). The provider's email
  may differ from the account's; `email` is always the VitNode account's.

It does not fire on the first sign-in through a provider (that is a
`user.created`) or on a later sign-in through an identity that is already
linked.

**A listener would** notify the account owner that a new sign-in method was
added, or audit-log the link with the envelope's `actor`.

</Accordion>
<Accordion title="user.sso.unlinked">

Emitted by `SsoConnectionModel.disconnect` after the connection and its profile
sync settings are deleted. Nothing is revoked at the provider - the member still
has to remove the app there if they want to.

**A listener would** email the member that a sign-in method was removed.

</Accordion>
<Accordion title="user.sso.profile_synced">

Emitted when at least one profile field actually changed because of a provider.
Fields that were missing, not allowed or already equal are left out, and an
avatar that failed to download never counts. A name change also emits
`user.updated`, and an avatar change emits `user.avatar.updated`.

**A listener would** refresh a search index or a cached member card.

</Accordion>
<Accordion title="user.email.verified">

Emitted once an unconfirmed address becomes confirmed: when a member clicks
the link from their sign-up email, when they complete a password reset (the
reset link went to the same mailbox), or when staff press **Verify Email** on
the AdminCP user page. A reset on an account that was already confirmed emits
nothing here. See
[Email Verification](/docs/dev/working-with-users/email-verification).

**A listener would** send a welcome email or unlock a "verified member" badge.

</Accordion>
<Accordion title="user.password.updated">

Emitted after a new password hash is stored - when a member completes a
password reset, or when staff set one from the AdminCP user page. The staff
route answers `403` while password sign-in is turned off, so this never fires
for a password nobody could use. Both paths then sign the account out
everywhere, so `user.sessions.revoked` follows right after.

**A listener would** email the account owner that their password changed, and
use the envelope's `actor` to say whether they or an administrator did it.

</Accordion>
<Accordion title="user.sessions.revoked">

Emitted by `revokeSessions` once a user's sessions are deleted and their cached
copies dropped. It covers both session kinds - the site session and the AdminCP
session - and fires from every place that signs somebody out remotely: a member
ending one of their own devices, staff ending one device or all of them, and a
password change.

**A listener would** write a security audit entry, or warn the member when
staff signed them out.

</Accordion>
<Accordion title="user.sso.preferences_updated">

Emitted by `SsoConnectionModel.savePreferences` after the profile-field sources
and the per-provider sync switches are saved - from **Settings → Connected
accounts** or from the AdminCP user page. It fires on every successful save,
even when nothing changed.

<TypeTable
  type={{
    userId: {
      description: 'Id of the account the settings belong to.',
      type: 'number',
    },
    sources: {
      description:
        'The submitted source per profile field - a provider id, or `null` for managed manually. Fields left out were not changed.',
      type: "Partial<Record<'avatar' | 'firstName' | 'lastName', string | null>>",
    },
    sync: {
      description: 'The submitted sync-on-sign-in switch per provider id.',
      type: 'Record<string, boolean>',
    },
  }}
/>

**A listener would** audit-log who changed where an account's profile comes
from.

</Accordion>
<Accordion title="user.deleted (declared, never emitted)">

The name and payload live on the `VitNodeEvents` map so listeners type-check,
but **core never emits it**: there is no user-deletion flow yet. It is the
agreed-upon name for plugins that implement account deletion themselves, and
core will emit it once deletion lands.

</Accordion>
<Accordion title="role.created and role.updated">

Emitted after a role is created or edited in the AdminCP, including its
translated names - those live in `core_languages_words`, so the payload has no
name field to carry.

**A listener would** provision plugin-side permission defaults for a new role,
or refresh an externally-cached permission matrix when one changes.

</Accordion>
<Accordion title="role.deleted">

Emitted after the delete transaction commits. Its translated names are removed
with it, and its secondary-role assignments and staff-permission entries are
dropped by database cascade. Members point at their primary role through a
`NOT NULL` restricted foreign key, so anyone in the role is reassigned
**before** the delete - by the time this fires, no user references it.

**A listener would** clean up plugin-owned rows keyed by role id. The role row
is already gone, so key the cleanup off `payload.roleId` rather than re-reading
`core_roles`:

```ts title="Example: clean up plugin data on role deletion"
export const roleCleanupListener = buildEventListener({
  event: 'role.deleted',
  name: 'cleanup-role-settings',
  handler: async (c, payload) => {
    await c
      .get('db')
      .delete(shop_role_settings)
      .where(eq(shop_role_settings.roleId, payload.roleId))
  },
})
```

</Accordion>
</Accordions>

## Navigation events [#navigation-events]

Four names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts`. Every one fires **after** the
header menu or the bottom bar changed in the AdminCP and after the cached menus were expired, so a
listener that re-reads the menu sees the new state.

| Event                  | Payload               | Fires when                                                                      |
| ---------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `navigation.created`   | `{ navigationId }`    | A prebuilt page or a custom link is added to the header menu or the bottom bar  |
| `navigation.updated`   | `{ navigationId }`    | A menu item's title, description, URL, new-tab setting or placement is edited   |
| `navigation.reordered` | `{ items, location }` | One menu is saved in a new order or nesting - `items` is that menu's whole tree |
| `navigation.deleted`   | `{ navigationId }`    | A menu item is removed, together with its translations                          |

The item's translated title and description live in `core_languages_words`, so
the payload carries only the id. On `deleted` the row is already gone; key any
cleanup off `payload.navigationId`.

**A listener would** purge a CDN's cached HTML, or log who changed the menu
and when.

</Accordion>
<Accordion title="navigation.reordered">

Fires after a drag-and-drop in the AdminCP saved a menu. The payload is that
entire menu as the administrator now sees it, one level deep - the header menu
or the bottom bar, never both.

</Accordion>
</Accordions>

## Notification events [#notification-events]

Eight names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts`. Seven of them fire **after** an
administrator's change in [AdminCP → Notifications](/docs/dev/notifications/admincp)
has been saved, and the envelope's `actor` is that administrator.
`notifications.preferences_updated` is about one member: it fires when their
own preferences are saved, by them or by staff on their AdminCP user page.

| Event                               | Payload               | Fires when                                                                 |
| ----------------------------------- | --------------------- | -------------------------------------------------------------------------- |
| `notifications.type.updated`        | `{ typeId }`          | What a type does by default (list, push, email, member can edit) changes   |
| `notifications.preferences_updated` | `{ userId, typeIds }` | One member's preferences are saved - `typeIds` are the types in the save   |
| `notifications.preferences_reset`   | `{ members }`         | **Reset all members to defaults** ran - `members` is how many were reset   |
| `notifications.paused`              | `{}`                  | Notifications were paused from the danger zone                             |
| `notifications.resumed`             | `{ requeuedEvents }`  | Notifications were resumed - `requeuedEvents` waited while paused          |
| `notifications.emails_cancelled`    | `{ count }`           | Queued emails were cancelled - `count` is how many deliveries were skipped |
| `notifications.read_all`            | `{ items, members }`  | Everything was marked as read for everyone                                 |
| `notifications.deleted_all`         | `{ items }`           | Every member's notifications were deleted                                  |

**A listener would** post an audit entry to your staff channel when someone
pauses, deletes or resets everything, or note when staff changed how a single
member is notified.

## Moderation events [#moderation-events]

Seven names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts` and emitted by core with
`pluginId: "@vitnode/core"`. Each fires **after** its database transaction
commits. The envelope's `actor` is the reporter for `created` and the
moderator for the rest. Adding an internal note emits nothing. See
[Moderation](/docs/dev/moderation).

| Event                        | Payload                                                | Fires when                                                                  |
| ---------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
| `moderation.report.created`  | `{ reportId, pluginId, targetType, targetId, reason }` | A signed-in user files a report                                             |
| `moderation.report.assigned` | `{ reportId, assigneeId, previousAssigneeId }`         | A moderator takes, reassigns or unassigns a report. `assigneeId` may be `null` |
| `moderation.report.action`   | `{ reportId, action, pluginId, targetType, targetId }` | A content action from the ModCP changed the content. `action` is `hide` or `unhide` |
| `moderation.report.resolved` | `{ reportId, resolution }`                             | A report is closed with an outcome                                          |
| `moderation.report.reopened` | `{ reportId }`                                         | A closed report is reopened                                                 |
| `moderation.report.note_updated` | `{ reportId, noteId }`                             | A moderator edits an internal note                                          |
| `moderation.report.note_deleted` | `{ reportId, noteId }`                             | A moderator deletes an internal note                                        |

A hide or restore from the ModCP also emits the content type's own
`content.{id}.hidden` or `unhidden` event, because it goes through the same
visibility service as the AdminCP.

**A listener would** notify a staff channel when a report arrives, or keep a
per-moderator count of resolved reports.

## AI events [#ai-events]

Declared in `VitNodeEvents` in `packages/vitnode/src/api/models/events.ts`.
The two `ai.run.*` events are emitted by the shared AI runner (see
[AI Actions](/docs/dev/ai/actions)). They fire **after** the run was settled,
so its cost and points are already in the history when a listener reads it. A
failing listener never breaks the run - or the ALT write.

| Event               | Payload                                              | Fires when                                                                                                   |
| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `ai.run.completed`  | `{ actionKey, actorType, runId, userId }`            | A managed AI run delivered a valid result                                                                    |
| `ai.run.failed`     | `{ actionKey, actorType, errorCode, runId, userId }` | A run ended without a valid result: provider failure, cancel, bad output                                     |
| `files.alt.updated` | `{ fileId, languageCodes, origin }`                  | An image's default ALT text was written - by [automatic ALT text](/docs/dev/ai/automatic-alt) or by a person |

`userId` is `null` for system work such as automatic ALT text. Prompts and
outputs are never part of the payload.

`files.alt.updated` fires after the `core_files_alt` rows were written.
`languageCodes` lists only the languages that actually changed, and `origin` is
`"ai"` for the background job or `"human"` for `PUT /admin/files/{id}/alt`.
Removing a language's ALT text emits nothing.

**A listener would** post a notice when an editor's AI suggestion fails, count
AI usage per plugin in your own analytics, or purge cached pages that render an
image whose ALT text just changed.

## Page layout events [#page-layout-events]

One name, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts`. It fires **after** the layout row
has been written, and not at all when a save changed nothing.

| Event                      | Payload                    | Fires when                                                                            |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------------------- |
| `core.page-layout.updated` | `{ pageId, changedZones }` | Somebody saves widget changes on an [editable page](/docs/dev/widgets/editable-pages) |

Emitted by `PUT /pages/layout` once the one `core_page_layouts` row for that
page has been written. A page's layout is stored as overrides only, so
`changedZones` names the zones whose override actually moved - not every zone
the editor happened to send, and not the zones still sitting on the defaults
their `defineEditablePage` declaration ships.

A save that changes nothing writes nothing and emits nothing, so a listener
never fires for a no-op. Saving a zone back to its shipped default removes that
override, which counts as a change and is reported here.

**A listener would** purge whatever the front end caches for that page. The
layout is read by page id, so the id in the payload is the whole cache key:

```ts title="Example: expire a cached page after a layout change"
export const pageLayoutCacheListener = buildEventListener({
  event: 'core.page-layout.updated',
  name: 'expire-page-cache',
  handler: async (c, payload) => {
    await c.get('cache')?.delete(`page:${payload.pageId}`)
  },
})
```

</Accordion>
</Accordions>

## Content Engine events [#content-engine-events]

Every content type declared with the
[Content Engine](/docs/content-engine) gets its own event names, built from
its id: `content.<id>.<action>`. For the example plugin's `example.article`
that means `content.example.article.created`, and for the blog's `blog.post` it
means `content.blog.post.created`.

Every payload's `contentId` (and `sourceId` and `duplicatedFromId`) has the
content type's [id type](/docs/content-engine/id-strategy): a `number` for the
default `serial` strategy, a `string` for `uuid` and `bigint`. A bigint id
arrives as its exact decimal string, so never pass it through `Number()`.

Which actions exist depends on what the definition opts into. A content type
that declares nothing beyond its fields emits three events; one that declares
everything emits nineteen.

| The definition declares              | Events it adds                                                      |
| ------------------------------------ | ------------------------------------------------------------------- |
| nothing extra (always)               | `created`, `updated`, `deleted`                                     |
| `publication`                        | `published`, `unpublished`                                          |
| `editorial`                          | `restored`                                                          |
| `editorial.scheduling`               | `scheduled`, `schedule_cancelled`                                   |
| `localization`                       | `translation_created`, `translation_updated`, `translation_deleted` |
| `localization` **and** `publication` | `translation_published`, `translation_unpublished`                  |
| `localization` **and** `editorial`   | `translation_restored`                                              |
| `delivery`                           | `delivery_slug_changed`, `delivery_redirect_created`                |
| `duplication`                        | `duplicated`                                                        |
| `visibility`                         | `hidden`, `unhidden`                                                |

The gating is in the types, not just at runtime: `ContentEventsFor` expands to
literal keys only for the features the definition enables. The example plugin's
`example.article` declares `editorial`, so
`content.example.article.restored` type-checks; `example.category` is one text
field and nothing else, so `content.example.category.restored` is not a key on
the map and a listener for it does not compile.

### Record events [#record-events]

| Event                | Payload                                                                     | Fires when                                                                        |
| -------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `created`            | `{ contentId }`                                                             | A record is inserted                                                              |
| `updated`            | `{ contentId, changedFields }`                                              | At least one declared field actually changed                                      |
| `deleted`            | `{ contentId }`                                                             | A record is deleted                                                               |
| `published`          | `{ contentId, publishedAt, scheduledBy?, scheduleId? }`                     | A record becomes publicly visible - interactively or when a schedule fires        |
| `unpublished`        | `{ contentId, scheduledBy?, scheduleId? }`                                  | A record is withdrawn                                                             |
| `restored`           | `{ contentId, changedFields, version, revisionId, restoredFromRevisionId }` | A record is rolled back to an earlier revision - emitted **instead of** `updated` |
| `scheduled`          | `{ contentId, action, actorUserId, scheduledFor, scheduleId }`              | A publish or unpublish is booked for later                                        |
| `schedule_cancelled` | `{ contentId, action, actorUserId, scheduleId }`                            | A pending booking is called off                                                   |
| `duplicated`         | `{ actorUserId, contentId, contentTypeId, sourceId }`                       | A record was copied into a new draft, right after the copy's own `created`        |
| `hidden`             | `{ actorUserId, contentId, hiddenAt }`                                      | A visible record is taken off the public site without being unpublished           |
| `unhidden`           | `{ actorUserId, contentId }`                                                | A hidden record is made visible again                                             |

<TypeTable
  type={{
    contentId: {
      description: 'Id of the created, updated or deleted row.',
      type: 'ContentIdOf<TDefinition>',
    },
    changedFields: {
      description:
        "Update only - the fields whose value actually changed, narrowed to this content type's own field names. An update that changes nothing emits no event at all.",
      type: 'ContentFieldName<TDefinition>[]',
    },
    duplicatedFromId: {
      description:
        'Set on the `created` of a duplicate, with the id of the record it was copied from. Absent for an ordinary create, so a listener can tell copies apart without waiting for `duplicated`.',
      type: 'ContentIdOf<TDefinition>',
    },
  }}
/>

**A listener would** mirror the row into a plugin-owned projection, reindex it
for an external search engine, or purge a CDN entry. `changedFields` is what
lets it skip the work when the field it cares about did not move.

</Accordion>
<Accordion title="published and unpublished">

`publishedAt` is when the record went live for the **first** time and is never
rewritten by a later unpublish and republish. `scheduledBy` and `scheduleId`
are present only when a booking caused the transition; an interactive publish
carries neither.

<TypeTable
  type={{
    contentId: {
      description: 'Id of the record whose visibility moved.',
      type: 'ContentIdOf<TDefinition>',
    },
    publishedAt: {
      description:
        'Published only - when the record first went live. Declared as a Date, but omitted when the engine could not read one back off the row, so guard for undefined.',
      type: 'Date',
    },
    scheduledBy: {
      description:
        'Only when a schedule fired this - the staff member who booked it. Absent on an interactive publish, because the actor of a scheduled run genuinely is the system.',
      type: 'null | number',
    },
    scheduleId: {
      description:
        'Only when a schedule fired this - the booking, which doubles as the idempotency key across the effects task retries.',
      type: 'number',
    },
  }}
/>

**A listener would** announce the record (a newsletter, a social post, a
realtime toast), add or remove it from an external index, or expire a cache
that only holds public rows. Because the same publish can arrive twice, key
anything that must happen once off `scheduleId` - see
[A scheduled event may arrive twice](#a-scheduled-event-may-arrive-twice).

</Accordion>
<Accordion title="restored">

A rollback to an earlier revision's field values. It carries `changedFields`
exactly like `updated`, so porting an `updated` listener is a rename rather
than a rewrite - which is why a restore emits one event and not both.

<TypeTable
  type={{
    contentId: {
      description: 'Id of the restored record.',
      type: 'ContentIdOf<TDefinition>',
    },
    changedFields: {
      description:
        'The fields the rollback moved, in the same shape `updated` uses.',
      type: 'ContentFieldName<TDefinition>[]',
    },
    version: {
      description:
        'The version the record holds after the restore. Always a new number; the restored version is never reinstated.',
      type: 'number',
    },
    revisionId: {
      description: 'The revision this restore itself created.',
      type: 'number',
    },
    restoredFromRevisionId: {
      description: 'The revision the values were taken from.',
      type: 'number',
    },
  }}
/>

**A listener would** do exactly what its `updated` listener does. A restore
never moves `status`, `publishedAt` or `hiddenAt`, so nothing watching
visibility has to handle it.

</Accordion>
<Accordion title="scheduled and schedule_cancelled">

Booking a transition changes no field value, so it consumes no version and
writes no revision - `scheduled` is a different fact from `published`. When the
booking fires, the transition emits the ordinary `published` or `unpublished`
with `scheduleId` and `scheduledBy` set.

<TypeTable
  type={{
    contentId: {
      description: 'Id of the record the booking is about.',
      type: 'ContentIdOf<TDefinition>',
    },
    action: {
      description: 'Which transition was booked, or cancelled.',
      type: '"publish" | "unpublish"',
    },
    actorUserId: {
      description:
        'The staff member who booked or cancelled it. Note the name: the same person is called `scheduledBy` on the published/unpublished payloads.',
      type: 'null | number',
    },
    scheduledFor: {
      description: 'Scheduled only - when the transition will happen.',
      type: 'Date',
    },
    scheduleId: {
      description:
        'The schedule row. Always present on both events, and the id the eventual published/unpublished will carry.',
      type: 'number',
    },
  }}
/>

**A listener would** show an editorial calendar, warn an author that two
bookings collide, or pre-warm a render shortly before `scheduledFor`.

</Accordion>
<Accordion title="duplicated">

A [duplicate](/docs/content-engine/duplicate-content) first emits the copy's
ordinary `created` (with `duplicatedFromId`) and one `translation_created` per
copied language, then `duplicated`. Indexing already ran for `created`, so
`duplicated` is a notification only.

<TypeTable
  type={{
    actorUserId: {
      description:
        'The staff member who asked for the copy, or null for the system or an API key.',
      type: 'null | number',
    },
    contentId: {
      description: 'Id of the new draft.',
      type: 'ContentIdOf<TDefinition>',
    },
    contentTypeId: {
      description: 'The content type id, such as `blog.post`.',
      type: 'string',
    },
    sourceId: {
      description:
        'Id of the record that was copied. It is only read, never changed.',
      type: 'ContentIdOf<TDefinition>',
    },
  }}
/>

**A listener would** credit the original author in an audit log, or link the
copy to its source in a plugin-owned table.

</Accordion>
<Accordion title="hidden and unhidden">

[Hiding](/docs/content-engine/content-visibility) takes a record off the public
site without touching `status` or `publishedAt`, so a hidden record emits
neither `unpublished` nor, when unhidden, `published`. Hiding a record that is
already hidden emits nothing.

<TypeTable
  type={{
    actorUserId: {
      description: 'The staff member who hid or unhid it, or null for the system.',
      type: 'null | number',
    },
    contentId: {
      description: 'Id of the record.',
      type: 'ContentIdOf<TDefinition>',
    },
    hiddenAt: {
      description: 'When the record was hidden. Sent with `hidden` only.',
      type: 'Date',
    },
  }}
/>

**A listener would** purge a CDN entry, pull the record from an external
search engine, or tell the author that a moderator took their article down.
Hiding a draft emits the event too, though nothing public changed.

</Accordion>
</Accordions>

### Translation events [#translation-events]

A content type with [`localization`](/docs/content-engine/localization)
emits one event per translation mutation, in addition to the record events
above. Every one of them carries `locale` and `languageId`, so a listener never
has to go and ask which language moved.

| Event                     | Payload                                                          | Fires when                                |
| ------------------------- | ---------------------------------------------------------------- | ----------------------------------------- |
| `translation_created`     | `{ contentId, locale, languageId, version, revisionId? }`        | A language's translation row is written   |
| `translation_updated`     | `{ ...base, changedFields }`                                     | A language's localized fields changed     |
| `translation_deleted`     | `{ ...base }`                                                    | A language's translation is removed       |
| `translation_published`   | `{ ...base, publishedAt }`                                       | One language becomes publicly visible     |
| `translation_unpublished` | `{ ...base }`                                                    | One language is withdrawn                 |
| `translation_restored`    | `{ ...base, changedFields, revisionId, restoredFromRevisionId }` | One language is rolled back to a revision |

<TypeTable
  type={{
    contentId: {
      description:
        'Id of the record the translation belongs to - the base row, not the translation row.',
      type: 'ContentIdOf<TDefinition>',
    },
    locale: {
      description:
        'The canonical core_languages.code the mutation was made in. Always present.',
      type: 'string',
    },
    languageId: {
      description:
        'core_languages.id, for a listener joining against the languages table directly.',
      type: 'number',
    },
    version: {
      description:
        'The version *this translation* holds after the mutation - each language has its own.',
      type: 'number',
    },
    revisionId: {
      description:
        'The revision this mutation wrote. Absent - not null - for a localized content type without `editorial`, which keeps no history, so `"revisionId" in payload` is how a listener checks.',
      type: 'number',
    },
    changedFields: {
      description:
        'Updated and restored only - localized field names this write moved. Never a shared field.',
      type: 'ContentLocalizedFieldName<TDefinition>[]',
    },
    publishedAt: {
      description:
        'Published only - when this language first went live. Nullable, unlike its record-level counterpart.',
      type: 'Date | null',
    },
    restoredFromRevisionId: {
      description:
        "Restored only - the revision the values came from, always one of this locale's own.",
      type: 'number',
    },
  }}
/>

**A listener would** invalidate one locale's cache, reindex one language's
search document, or tell a translation vendor that the Polish copy moved.

</Accordion>
<Accordion title="Why translations are not folded into updated">

A shared update and a Polish translation update are different domain facts with
different consequences: one invalidates every language, the other invalidates
one. A listener that had to inspect `changedFields` to tell them apart would get
it wrong the first time a field was renamed - so `changedFields` on a
translation event names localized fields only, and never a shared one.

</Accordion>
</Accordions>

### Delivery events [#delivery-events]

A content type with
[`delivery`](/docs/content-engine/public-pages) emits two more
when its public URL moves. Both arrive **alongside** the lifecycle event that
moved it - `updated`, `restored`, a publication transition or a
`translation_*` - never instead of one: a field moving and a URL moving are
different facts with different audiences.

| Event                       | Payload                                                                  | Fires when                                                    |
| --------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
| `delivery_slug_changed`     | `{ contentId, slug, previousSlug, previousPath, canonicalPath, locale }` | The canonical public path is different from what it was       |
| `delivery_redirect_created` | `{ contentId, previousSlug, previousPath, canonicalPath, locale }`       | A path that had genuinely been live now answers as a redirect |

<TypeTable
  type={{
    contentId: {
      description: 'Id of the record whose URL moved.',
      type: 'ContentIdOf<TDefinition>',
    },
    slug: {
      description: 'Slug changed only - the slug the record answers to now.',
      type: 'string',
    },
    previousSlug: {
      description:
        'The slug it answered to before. Declared nullable, but populated on both events in practice: neither fires unless the slug moved from one real value to another, so a record arriving at its first slug emits neither of them.',
      type: 'null | string',
    },
    previousPath: {
      description:
        'The public path it answered to before, spelled by the localized URL rules, e.g. /pl/artykuly/stary-slug (or /artykuly/stary-slug on a Polish domain). A path, never an origin. Nullable on delivery_slug_changed for the same declared reason, populated for the same real one, and always a string on delivery_redirect_created.',
      type: 'null | string',
    },
    canonicalPath: {
      description:
        'The public path it answers to now, and where the historical one redirects. Same shape as previousPath: locale prefix and translated segments applied, no origin.',
      type: 'string',
    },
    locale: {
      description:
        'The language this URL belongs to, or null when the slug is shared - a content type that is not localized, or a localized one whose slug lives on the base row.',
      type: 'null | string',
    },
  }}
/>

**A listener would** purge a CDN entry, write to an edge redirect table, or tell
an external search engine the address changed. Without this event it would have
to inspect `changedFields` for a slug field whose name it cannot know.

</Accordion>
<Accordion title="Why a redirect is a separate event">

`delivery_redirect_created` fires only when the old address had genuinely been
**publicly addressable** - the engine has a retired history row to prove it. An
article whose slug was corrected three times while it was still a draft emits
three `delivery_slug_changed` and not one redirect; a published article that
moves emits one of each. That is the difference between "a URL now needs a
redirect" and "somebody edited a field".

There is deliberately no sitemap event either: every mutation that changes a
sitemap line already emits `published`, `unpublished`, `deleted` or one of these
two, and a third carrying no new information would be one more thing to keep
consistent for no listener's benefit.

</Accordion>
</Accordions>

### A scheduled event may arrive twice [#a-scheduled-event-may-arrive-twice]

Announcements for a scheduled transition run in a durable
[queue task](/docs/dev/advanced/queue) that retries whenever the event, the
search write or a cache origin failed - and a retry re-emits an event some
listeners already received. Delivery is **at-least-once**, deliberately: the
alternative is a transactional outbox, which the engine does not have.

A listener whose work must happen exactly once keys off `scheduleId`, which is
stable across every attempt at the same booking:

```ts
handler: async (c, payload) => {
  if (payload.scheduleId && (await alreadyDone(payload.scheduleId))) return

await sendTheAnnouncement(payload.contentId)
}
```

An interactive publish is emitted once, by the route that performed it, and
carries no `scheduleId`.

The other way out is an idempotency key on whatever the listener writes. A
notification published with `` idempotencyKey: `post:${payload.contentId}` ``
turns a second run into a no-op. See
[Idempotency keys](/docs/dev/notifications/publishing#choose-an-idempotency-key).

### The envelope's owner is the content type's plugin [#the-envelopes-owner-is-the-content-types-plugin]

`pluginId` on the envelope answers "whose event is this", not "who was running
at the time". Those come apart the moment something happens on a schedule: core
owns the queue handler, so `c.get('plugin')` says `@vitnode/core`, while
`content.example.article.published` belongs to the example plugin as much as it
ever did.

```text
queue task owner    @vitnode/core        ← who runs the handler
event envelope      @vitnode/example     ← who owns the content type
```

The engine passes the owner explicitly on every emit, so ownership does not
depend on which route module or queue handler invoked it. Your own code can do
the same when it emits on someone else's behalf:

```ts
await c.get('events').emit('blog.post.created', payload, {
  pluginId: '@vitnode/blog', // [!code ++]
})
```

Omit the option and nothing changes: the envelope falls back to
`c.get('plugin')` and then to `@vitnode/core`.

### Failures are reported, not thrown [#failures-are-reported-not-thrown]

`emit()` reports rather than throws. Listeners run after the write it describes
has committed, and a broken listener is not a reason to tell somebody their save
failed - so a failure comes back in the result instead, and is written to
`core_logs` twice over: once per listener by the transport
(`Event listener "plugin:module:listener" for "<event>" failed: ...`), and once
as a JSON summary behind the greppable `[content-effects]` prefix by whichever
effects helper emitted it - the editorial, translation, delivery and scheduled
paths. A plain `created`/`updated`/`deleted` on a content type without
`editorial` goes straight to the transport, so it produces the first line only.

```ts
const result = await c.get('events').emit('blog.post.created', payload)

result.delivered // listeners that ran
result.failures // [{ pluginId, module, listener, error }]
```

Interactive routes ignore that result on purpose, because the mutation succeeded
either way. Background work usually should not: the scheduled-effects task
inspects `failures` and retries the whole delivery when it is non-empty.

{/* Image prompt: A screenshot of the VitNode AdminCP debug panel at /admin/core/debug, dark theme, 1440x900, showing one red "error" log row whose content is the JSON line [content-effects] {"action":"published","contentTypeId":"blog.post","delivered":1,"eventId":"6f1c...","failures":[{"error":"fetch failed","listener":"@acme/shop:orders:mirror-post"}],"itemId":42}. */}

<Callout type="warn" title="The generated routes emit, the services do not">
  A generated route emits one lifecycle event per successful mutation, after the
  database write has returned - plus the delivery pair when the URL moved with
  it. A failed validation, a delete blocked by a foreign key, a no-op update, a
  no-op publish and a restore that changed nothing all emit nothing. Calling
  `service.publish()` - or any other content service method - directly changes
  the database and emits **nothing**; that code owns its own follow-up. See
  [Services and API](/docs/content-engine/services).
</Callout>

## Content container events [#content-container-events]

Four names, declared in `VitNodeEvents` in
`packages/vitnode/src/api/models/events.ts` and shared by every
[container collection](/docs/content-engine/containers). Each fires **after**
the write's transaction has committed. A refused write, such as deleting a board
that still has discussions, emits nothing, and so does an update that changes
nothing.

| Event                       | Payload                                                                     | Fires when                                                   |
| --------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `content.container.created` | `{ definitionId, pluginId, containerId, parentId }`                         | A container is created                                       |
| `content.container.updated` | `{ definitionId, pluginId, containerId, parentId, changedFields }`          | Its name, slug or a metadata field actually changed          |
| `content.container.moved`   | `{ definitionId, pluginId, containerId, parentId, fromParentId, position }` | It moved to another parent, another position, or both        |
| `content.container.deleted` | `{ definitionId, pluginId, containerId, parentId }`                         | An empty container is deleted                                |

Emitted by `createContentContainerService`, so the AdminCP routes and your own
code that uses the service emit the same events. Siblings renumbered by a move
or a delete do not get events of their own.

**A listener would** rebuild a navigation menu kept outside VitNode, or post to
a staff channel when a board is deleted:

```ts title="Example: announce deleted boards"
export const boardDeletedListener = buildEventListener({
  event: 'content.container.deleted',
  name: 'announce-deleted-board',
  handler: async (c, payload) => {
    if (payload.definitionId !== 'example.boards') return

await c.get('log').warn(`Board ${payload.containerId} was deleted`)
  },
})
```

</Accordion>
</Accordions>

## Blog events (`@vitnode/blog`) [#blog-events-vitnodeblog]

<Callout type="warn" title="These six names are compatibility adapters">
  The blog runs on the [Content Engine](/docs/content-engine), so the events
  that describe what actually happened are `content.blog.post.*` and
  `content.blog.category.*` - they carry changed fields, revision ids,
  publication transitions, per-locale translation events and slug history. The
  six names below are re-emitted from those by listeners registered on the
  plugin's own `admin` module, so existing consumers keep working. Prefer the
  `content.*` ones for anything new. A duplicated article re-emits
  `blog.post.created` once; `duplicated`, `hidden` and `unhidden` have no blog
  adapter.
</Callout>

| Event                   | Payload                   | Re-emitted from                 |
| ----------------------- | ------------------------- | ------------------------------- |
| `blog.post.created`     | `{ postId, categoryId }`  | `content.blog.post.created`     |
| `blog.post.updated`     | `{ postId, categoryId }`  | `content.blog.post.updated`     |
| `blog.post.deleted`     | `{ postId }`              | `content.blog.post.deleted`     |
| `blog.category.created` | `{ categoryId }`          | `content.blog.category.created` |
| `blog.category.updated` | `{ categoryId }`          | `content.blog.category.updated` |
| `blog.category.deleted` | `{ categoryId, postIds }` | `content.blog.category.deleted` |

### blog.post.created and blog.post.updated [#blogpostcreated-and-blogpostupdated]

The adapter reads the article's categories back to fill in `categoryId`, so a
record deleted in between is simply not announced - and so is one with no
categories yet.

**A listener would** push a realtime "new post" notification, ping a webhook
(from a queue task) that shares the post to social media, invalidate an external
cache, or keep plugin-owned derived data such as related posts in sync.

### blog.post.deleted [#blogpostdeleted]

No `categoryId`, unlike created and updated: the row is gone by the time this is
emitted, so there is nothing left to read it from - and inventing one would put
a wrong id into an audit trail. A listener that needs the category should watch
`content.blog.post.deleted` and keep its own index.

**A listener would** remove the post from an external index or feed.

### blog.category.created and blog.category.updated [#blogcategorycreated-and-blogcategoryupdated]

**A listener would** keep a navigation menu or an externally-cached category
tree in sync, or notify an external CMS of a taxonomy change.

### blog.category.deleted [#blogcategorydeleted]

**A listener would** drop the category from a cached navigation tree. It never
has to fan out to the category's posts, because a category with posts cannot be
deleted in the first place.

## Gotchas [#gotchas]

<Callout type="warn" title="Core's user and role events are not deduplicated">
  The AdminCP user `PATCH` emits `user.updated` whenever it succeeds, even if
  every field was written with the value it already had, and the role routes
  behave the same way. Only the Content Engine's `updated` is gated on a real
  diff. A listener that does expensive work should compare before acting.
</Callout>

<Callout type="warn" title="A content type is only typed once its plugin grafts it">
  Events fire at runtime for every registered content type, but the names appear
  on `VitNodeEvents` only where the owning plugin declares
  `ContentEventsFor<typeof myContentType>`. The example plugin grafts
  `example.article` and `example.category` but not its two localized fixtures,
  so `content.example.localized-article.created` really is emitted and still
  cannot be given a type-checked listener. If your event name does not
  autocomplete, that declaration is what is missing - see
  [Plugin registration](/docs/content-engine/plugin-files).
</Callout>

<Callout type="warn" title="Editorial payloads carry more than they declare">
  A content type with `editorial` goes through the shared effects helper, which
  stamps `version` and `revisionId` onto **every** payload it emits, including
  `created` and `deleted`. Neither field is on the declared type for those
  actions, so treat them as an implementation detail rather than a contract -
  the fields you can rely on are the ones in the tables above.
</Callout>

<Callout type="warn" title="Names shift between scheduled and published">
  The person who booked a transition is `actorUserId` on `scheduled` and
  `schedule_cancelled`, and `scheduledBy` on the `published` and `unpublished`
  that the booking eventually fires. Same human, two keys.
</Callout>

## Deliberately not emitted yet [#deliberately-not-emitted-yet]

High-frequency or consumer-less events are added only when a listener needs
them, so the catalog stays meaningful. There is currently no `user.signedIn`,
`user.passwordResetRequested`, or `file.uploaded`. If you need one, open an
issue or PR - adding an event is a one-line `emit` plus an entry in the
`VitNodeEvents` map. (`user.deleted` is the special case: it is already on the
map, and waits on core growing a user-deletion flow.)

Live editing is quiet on the bus too. Taking or giving back a field lock,
autosaving the shared draft and every keystroke in a co-edited rich text field
happen many times a minute and change nothing anyone outside the form relies
on, so none of them is an event. What does reach the bus is the commit: when
someone presses **Save**, the record emits its usual `updated` (and its
translations theirs), exactly as it would without live editing.

## Next [#next]

# Custom Event Adapter (/docs/dev/events/custom-adapter)

By default, VitNode delivers domain events in-process on the originating machine. By implementing a custom `EventsApiPlugin`, you can forward events to an external message broker (Redis Streams, RabbitMQ, NATS) to fan them out across a distributed cluster.

## The `EventsApiPlugin` Interface [#the-eventsapiplugin-interface]

```ts
import type { Context } from "hono"
import type { EventEnvelope, EventEmitResult } from "@vitnode/core/api/models/events"

export interface EventsApiPlugin {
  name: string
  publish: (c: Context, envelope: EventEnvelope) => Promise<EventEmitResult>
}
```

---

## Quick start [#quick-start]

### 1. Build the Adapter [#1-build-the-adapter]

```ts title="apps/api/src/lib/events/redis-stream-adapter.ts"
import type { EventsApiPlugin } from "@vitnode/core/api/models/events"

export const RedisStreamEventsAdapter = (): EventsApiPlugin => ({
  name: "redis-stream",
  // [!code ++:13]
  publish: async (c, envelope) => {
    const redis = c.get("redis")
    if (redis) {
      await redis.xadd("vitnode:events", "*", "payload", JSON.stringify(envelope))
    }

return {
      eventId: envelope.eventId,
      status: "queued",
      delivered: 0,
      failures: [],
    }
  },
})
```

---

### 2. Register in API Configuration [#2-register-in-api-configuration]

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"
import { RedisStreamEventsAdapter } from "./lib/events/redis-stream-adapter"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:3]
  events: {
    adapter: RedisStreamEventsAdapter(),
  },
})
```

All calls to `c.get("events").emit()` will now publish events through your custom adapter.

## Learn More [#learn-more]

# Events (/docs/dev/events)

VitNode includes an in-process event bus accessible via `c.get("events")`. Events decouple features across plugins (e.g. sending a welcome email when a user registers) without direct inter-plugin dependencies.

## Quick start [#quick-start]

### 1. Emit an Event [#1-emit-an-event]

Emit events from any Hono route or service after a database write:

```ts
await c.get("events").emit("user.created", {
  userId: user.id,
  email: user.email,
  name: user.name,
  emailVerified: user.emailVerified,
})
```

---

### 2. Subscribe with an Event Listener [#2-subscribe-with-an-event-listener]

Define a listener in your plugin:

```ts title="plugins/shop/src/api/lib/events.ts"
import { buildEventListener } from "@vitnode/core/api/lib/events"

export const welcomeListener = buildEventListener({
  event: "user.created",
  name: "send-welcome-email",
  handler: async (c, payload) => {
    await c.get("queue").dispatch({
      name: "send-welcome-email",
      payload: { userId: payload.userId, email: payload.email },
    })
  },
})
```

```ts title="plugins/shop/src/api/modules/orders/orders.module.ts"
import { buildModule } from "@vitnode/core/api/lib/module"
import { welcomeListener } from "../../lib/events"

export const ordersModule = buildModule({
  name: "orders",
  routes: [listOrdersRoute],
  events: [welcomeListener], // [!code ++]
})
```

---

## Declare Custom Event Types [#declare-custom-event-types]

Extend VitNode's global `EventMap` interface in your plugin so payload types are strictly enforced and autocompleted:

```ts title="plugins/shop/src/api/lib/events.ts"
export interface OrderPlacedPayload {
  orderId: number
  userId: number
  total: number
}

// [!code ++:7]
declare module "@vitnode/core/lib/events" {
  interface EventMap {
    "shop.order.placed": OrderPlacedPayload
  }
}
```

Now `emit("shop.order.placed", ...)` and `buildEventListener({ event: "shop.order.placed", ... })` are strictly type-checked.

---

## Delivery Guarantees [#delivery-guarantees]

## Learn More [#learn-more]

# Data Fetching (/docs/dev/fetcher)

In TanStack Start, data fetching bridges two execution environments: server-side rendering during SSR and in-app client navigation afterwards.

VitNode's universal `fetcher` from `@vitnode/core/tanstack/fetcher` eliminates duplicate transport logic. During SSR, it relays visitor cookies, IP addresses, and headers to the API; in the browser, it calls `/api/*` directly with `credentials: "include"`. One call, end-to-end type inference, zero drama.

## The universal call [#the-universal-call]

Call `fetcher` inline at the call site. The router automatically infers available modules, HTTP methods, arguments, and return types from your plugin's API registry:

```ts title="plugins/site-notes/src/features/notes/notes-query.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'

const response = await fetcher({
  plugin: '@acme/site-notes',
  method: 'get',
  module: 'notes',
  path: '/',
})

if (response.ok) {
  const { notes } = await response.json()
}
```

Four fields identify an endpoint:

| Field    | Description                                                    | Inferred from                        |
| :------- | :------------------------------------------------------------- | :----------------------------------- |
| `plugin` | Package name of the target plugin                              | App-configured plugin registry       |
| `module` | Module path under the plugin (e.g. `'notes'`, `'admin/notes'`) | Plugin's `buildApiPlugin` definition |
| `path`   | Route path declared inside the module (`'/'`, `'/{id}'`)       | Module's route declarations          |
| `method` | HTTP method declared for that path (`'get'`, `'post'`, etc.)   | Declared routes for that path        |

## Arguments: body, params, and query [#arguments-body-params-and-query]

The `args` object is required whenever a route declares Zod schemas for parameters, queries, or request bodies:

```ts title="plugins/site-notes/src/features/notes/pin-note.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'

export const pinNote = async (id: string, pinned: boolean) => {
  const response = await fetcher({
    plugin: '@acme/site-notes',
    // [!code ++:4]
    args: {
      body: { pinned },
      params: { id },
    },
    method: 'post',
    module: 'notes',
    path: '/{id}/pin',
  })

if (response.status === 404) return null

// Narrowed to 200: typed as the pinned Note object
  return await response.json()
}
```

- `params` — Interpolated into path parameters like `/{id}`.
- `query` — Serialized into the URL query string (e.g. `?search=term&page=1`).
- `body` — Serialized as JSON.
- `formData` — Pass `formData` instead of `args.body` for file uploads.
- `captchaToken` — Pass `captchaToken` for captcha-protected endpoints.

## Type inference & compile checks [#type-inference--compile-checks]

The fetcher validates endpoints through `ApiPluginRegistry`. An invalid method, typo in the path, or missing parameter produces an immediate compile-time error:

```ts
await fetcher({
  plugin: '@acme/site-notes',
  // @ts-expect-error Type '"delete"' is not assignable to type '"get"'.
  method: 'delete',
  module: 'notes',
  path: '/',
})
```

The response is status-aware: `response.status` is typed as a union of declared HTTP codes (e.g. `200 | 404`). Once you narrow on `response.status`, `response.json()` automatically narrows to that status code's specific schema.

## How the registry types your calls [#how-the-registry-types-your-calls]

Each plugin exports a lightweight contract type from its `config.api.ts`:

```ts title="plugins/site-notes/src/config.api.ts"
import type { ApiPluginContract } from '@vitnode/core/lib/fetcher'

export type VitNodeApiPlugin = ApiPluginContract<
  ReturnType<typeof siteNotesApiPlugin>
>
```

`ApiPluginContract` strips away runtime internals (Hono handlers, database connections, and background workers) and extracts only what the compiler needs: the plugin ID, module paths, route endpoints, methods, and Zod schemas.

When you run `vite dev` or `vite build`, the `vitnode:plugin-routes` plugin automatically updates your app's `src/api-registry.gen.ts`:

```ts title="apps/web/src/api-registry.gen.ts"
import type { VitNodeApiPlugin as ApiPlugin0 } from '@acme/site-notes/config.api'

declare module '@vitnode/core/lib/fetcher/registry' {
  interface ApiPluginRegistry {
    '@acme/site-notes': ApiPlugin0
  }
}

export type { ApiPluginRegistry } from '@vitnode/core/lib/fetcher/registry'
```

<Callout type="warn" title="Types only, never a value">
  All imports in the registry use `import type`. This guarantees that
  server-side code, database credentials, and internal handlers never leak into
  the browser bundle. The actual API factory executes exclusively in
  `vitnode.api.config.ts`.
</Callout>

## Loading data in plugin routes [#loading-data-in-plugin-routes]

Plugin routes load data using `defineRoute({ load })` from `@vitnode/core/tanstack/plugin-routes`. The loader runs during SSR and client navigation, handing typed `loaderData` to the page component. Its context includes `queryClient`; the framework-neutral `definePluginRoute` from `@vitnode/core/routing` only receives `locale`:

```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'
import { defineRoute } from '@vitnode/core/tanstack/plugin-routes'
import { notesQuery } from '../features/notes/notes-query'

interface Note {
  id: string
  title: string
}

// [!code ++:8]
export const route = defineRoute({
  load: async ({ context }) => {
    return await context.queryClient.query({
      ...notesQuery(),
      staleTime: 'static',
    })
  },
})

const NotesPage = ({ loaderData }: PluginRoutePageProps<Note[]>) => {
  return (
    <div className="container mx-auto flex max-w-3xl flex-col gap-4 p-4">
      {loaderData.map((note) => (
        <h2
          key={note.id}
          className="text-xl font-semibold tracking-tight text-balance"
        >
          {note.title}
        </h2>
      ))}
    </div>
  )
}

export default NotesPage
```

`staleTime: "static"` makes the loader reuse an entry that is already cached instead of fetching again on every navigation. The entry refreshes when a mutation invalidates it, as shown below. See [Cache app data](/docs/dev/cache/app) for the full pattern.

## Mutations & cache invalidation [#mutations--cache-invalidation]

After creating, editing, or deleting records, call `queryClient.invalidateQueries` to refetch fresh data, then display a `sonner` toast notification:

```tsx title="plugins/site-notes/src/features/notes/use-create-note.ts"
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { fetcher } from '@vitnode/core/tanstack/fetcher'
import { toast } from 'sonner'
import { notesQueryKey } from './notes-query'

export const useCreateNote = () => {
  const queryClient = useQueryClient()

return useMutation({
    mutationFn: async (title: string) => {
      const response = await fetcher({
        plugin: '@acme/site-notes',
        args: { body: { title } },
        method: 'post',
        module: 'notes',
        path: '/',
      })

if (!response.ok) {
        throw new Error('Failed to create note.')
      }

return await response.json()
    },
    onSuccess: async () => {
      // Invalidate cache and trigger sonner toast
      await queryClient.invalidateQueries({ queryKey: notesQueryKey })
      toast.success('Note created successfully!')
    },
  })
}
```

## Built-in system queries [#built-in-system-queries]

Core provides three pre-warmed query hooks for common application state:

### Deployment configuration [#deployment-configuration]

`useMiddlewareConfigQuery()` reads public server capabilities without requiring an active session, allowing login and registration screens to adapt dynamically:

```tsx title="plugins/site-notes/src/pages/login-page.tsx"
import { useMiddlewareConfigQuery } from '@vitnode/core/tanstack/auth'

const LoginPage = () => {
  const { data: config } = useMiddlewareConfigQuery()

return (
    <div className="container mx-auto max-w-md p-4">
      {config.captcha ? <p>Captcha enabled</p> : null}
      {config.sso?.length ? <p>Social sign-in available</p> : null}
    </div>
  )
}

export default LoginPage
```

- `sso` — Enabled social login providers.
- `isEmail` — Whether an email adapter is configured (required for password reset).
- `captcha` — Public site key and provider type (`recaptcha` or `cloudflare`).
- `ai.models` — Configured AI models in the deployment.
- `isKnown` — `false` if the API was unreachable (`UNKNOWN_MIDDLEWARE_CONFIG`), ensuring login forms still render.

## Freshness constants [#freshness-constants]

VitNode provides standard stale times in `@vitnode/core/lib/query-freshness`:

## Universal vs. server-only fetcher [#universal-vs-server-only-fetcher]

`fetcher` from `@vitnode/core/tanstack/fetcher` is the universal client. For operations that run exclusively on the server (server functions, cron tasks, or external secrets), use `@vitnode/core/tanstack/fetcher/server`:

| Feature                            | Universal (`fetcher`) | Server-only (`fetcher/server`) | Description                                          |
| :--------------------------------- | :-------------------: | :----------------------------: | :--------------------------------------------------- |
| Standard queries & mutations       |           ✓           |               ✓                | End-to-end typed requests                            |
| `args`, `formData`, `captchaToken` |           ✓           |               ✓                | Request parameter serialization                      |
| `allowSaveCookies`                 |                       |               ✓                | Relays API `Set-Cookie` headers back to the browser  |
| `additionalHeaders`                |                       |               ✓                | Forwards internal credentials or custom headers      |
| `origin`                           |                       |               ✓                | Directs requests to an alternative upstream API host |

<Callout type="warn" title="Keep server code out of browser bundles">
  Import from `@vitnode/core/tanstack/fetcher/server` only inside `*.server.ts`
  files or `createServerFn` handlers. Value imports of backend factories or
  server fetchers should never reach client bundles.
</Callout>

## Browser-only requests with fetcherClient [#browser-only-requests-with-fetcherclient]

For client code that **never** executes on the server—such as browser event listeners, interactive dialogs, or framework-neutral utilities—call `fetcherClient` from `@vitnode/core/lib/fetcher-client`:

```ts title="plugins/site-notes/src/features/notes/client-actions.ts"
import { fetcherClient } from '@vitnode/core/lib/fetcher-client'

export const deleteNote = async (id: string) => {
  const response = await fetcherClient({
    plugin: '@acme/site-notes',
    args: { params: { id } },
    method: 'delete',
    module: 'notes',
    path: '/{id}',
  })

return response.ok
}
```

`fetcherClient` shares the exact same call signature and type inference as the universal `fetcher`, but is built exclusively for the browser with `credentials: "include"` and automatic rate-limiting notifications.

## Content Engine routes [#content-engine-routes]

Public routes created via [Content Engine](/docs/content-engine) (`publicApi`) are automatically typed under `module: "content/<path>"`:

```ts
const response = await fetcher({
  plugin: '@vitnode/blog',
  args: { params: { slug: 'welcome' } },
  method: 'get',
  module: 'content/posts',
  path: '/{slug}',
})
```

For generated AdminCP content modules where schemas are dynamic, use `rawFetcher` from `@vitnode/core/tanstack/fetcher` instead. See [Content Engine](/docs/content-engine) for defining content types, schema modeling, and generating CRUD APIs.

<Cards>
  <Card
    icon={<BoxesIcon />}
    title="Content Engine"
    description="Define content types, schemas, and typed public endpoints."
    href="/docs/content-engine"
  />
  <Card
    icon={<MapIcon />}
    title="Plugin Routes"
    description="Define route trees, lazy pages, loaders, and breadcrumbs."
    href="/docs/dev/routing"
  />
  <Card
    icon={<ServerIcon />}
    title="Server Functions"
    description="Implement server-only workflows, cookie relays, and background jobs."
    href="/docs/dev/server-functions"
  />
  <Card
    icon={<DatabaseIcon />}
    title="Cache"
    description="Learn frontend query cache and Redis domain caching."
    href="/docs/dev/cache"
  />
</Cards>

# Languages & Localization (/docs/dev/i18n)

VitNode provides full internationalization out of the box. Every package (`@vitnode/core` and plugins) maintains its own locale files, which VitNode merges per request: core strings first, plugin strings second, and your host app overrides last.

{/* Image prompt: Layered merge diagram showing @vitnode/core strings, plugin strings, and app overrides merging into a unified message tree with defaultLocale fallback. Dark theme, 1600x700. */}

## Quick start [#quick-start]

Add a new language in two CLI commands:

```bash tab="bun"
bun run vitnode i18n create de Deutsch
bun run vitnode i18n check
```

```bash tab="pnpm"
pnpm vitnode i18n create de Deutsch
pnpm vitnode i18n check
```

```bash tab="npm"
npx vitnode i18n create de Deutsch
npx vitnode i18n check
```

</Tabs>

`vitnode i18n create` adds the language to `src/vitnode.config.ts`, seeds a translation file per installed package, and registers the loaders in `src/locales/app.ts`. `vitnode i18n check` scans for missing or untranslated keys - including a file nobody imports, which is the usual reason a translation "does not apply".

| Command                  | What it does                                                                                  |
| ------------------------ | --------------------------------------------------------------------------------------------- |
| `vitnode i18n create`    | Add a language: seed its files and wire them into the config                                  |
| `vitnode i18n check`     | Report missing, unknown and unloaded translations (`--ci` fails on missing keys)              |
| `vitnode i18n update`    | Sync translation files with the default language's keys                                       |
| `vitnode i18n update-ai` | Translate strings still in the default language with an AI model (`--model`, `--concurrency`) |
| `vitnode i18n delete`    | Remove a language (`--yes` to skip the question)                                              |

Arguments skip their questions, so every command works in a script: without a terminal, a missing argument is an error (exit code `2`) rather than a prompt that waits forever. The older `i18n:create`-style names still work.

---

## Language Configuration [#language-configuration]

Locale metadata is plain data, so it lives in the browser-safe [shared config](/docs/dev/configuration) - one declaration, read by the router, the document shell and (in a single app) the API that sends your emails:

```ts title="apps/web/src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      // [!code ++:1]
      { code: 'de', name: 'Deutsch' },
    ],
    timeZone: 'UTC',
  },
  // ...
})
```

`timeZone` is explicit on purpose: your app renders on a server, and without one `use-intl` formats dates in whatever zone the server happens to run in - then warns that the client will disagree.

Because `buildConfig` keeps those codes as literal types, `'de'` is now part of your `Locale` union and a typo in `defaultLocale` is a type error.

---

## Where the loaders go [#where-the-loaders-go]

A `() => import('./de.json')` reads a file out of a package's build output, so it is the one part of i18n that must never reach a browser. Two files own it, and both are registered through the **server-only** config:

```ts title="apps/web/src/vitnode.server.config.ts"
export const vitNodeServerConfig = buildServerConfig({
  config: vitNodeConfig, // the locale list above
  messages: appMessages, // src/locales/app.ts
  packageMessages, // src/package-messages.gen.ts
})
```

<Callout type="warn" title="Not in vitnode.config.ts">
  Putting a loader in the shared config puts every plugin's AdminCP copy in your
  browser bundle, and makes your Vite build execute it. `vitnode i18n create`
  writes to the right file for you.
</Callout>

### The generated half [#the-generated-half]

Registering a plugin is the whole step. Every VitNode build reads the `plugins` in your `vitnode.config.ts`, takes the `localeFiles` each factory declares, and writes `src/package-messages.gen.ts` - core's own languages plus one block per plugin:

```ts title="apps/web/src/package-messages.gen.ts"
export const packageMessages: Record<string, LocaleMessagesMap> = {
  '@vitnode/core': {
    en: async () => await import('@vitnode/core/locales/en.json'),
  },
  '@acme/blog': {
    en: async () => await import('@acme/blog/locales/en.json'),
  },
}
```

Don't edit it - it is rewritten on every `dev` and `build`, which is why it sits in your `.gitignore`. Every specifier is a literal because that is the only kind a bundler can resolve: `import(pkg + '/locales/' + locale + '.json')` resolves to nothing. Every loader stays dynamic, so a language's JSON is a chunk of its own and the server loads only the locale a request asked for.

<Callout type="info" title="Packages ship English">
  `@vitnode/core` and the plugins in this repository ship `en` and nothing else.
  Every other language is the install's own, which is what the next section is
  for - and it is why a language you add is a file in **your** app rather than a
  pull request against a package.
</Callout>

---

## Overriding Strings [#overriding-strings]

Your own translations live in `apps/web/src/locales/{pluginId}/{locale}.json`, registered in `src/locales/app.ts`. The same file does both jobs: a whole language a package does not ship, and a reword of a string it does.

One file per package per language, holding that package's web **and** email strings together - an app keeps them in one tree where a package ships two, so the copy in an email cannot drift from the copy on the page.

To reword something core already says:

```json title="apps/web/src/locales/@vitnode/core/en.json"
{
  "core": {
    "global": {
      "save": "Update Changes"
    }
  }
}
```

```ts title="apps/web/src/locales/app.ts"
export const appMessages: AppMessagesMap = {
  // [!code ++:3]
  en: {
    '@vitnode/core': async () => await import('./@vitnode/core/en.json'),
  },
}
```

Because your app overrides are merged last, only the keys you specify are overwritten. Everything else continues to fall back to the package defaults.

A whole language looks exactly the same, because it is the same mechanism - this repository's own Polish is a pair of files nobody's `node_modules` contains:

```ts title="apps/web/src/locales/app.ts"
export const appMessages: AppMessagesMap = {
  pl: {
    '@vitnode/blog': async () => await import('./@vitnode/blog/pl.json'),
    '@vitnode/core': async () => await import('./@vitnode/core/pl.json'),
  },
}
```

If your app also serves the API, register the same map there so emails speak the language too - `i18n.messages` in `vitnode.api.config.ts`:

```ts title="apps/web/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  i18n: { ...vitNodeConfig.i18n, messages: appMessages }, // [!code highlight]
  // ...
})
```

---

### Your app's own strings [#your-apps-own-strings]

Copy that belongs to no package - your landing page, say - gets a namespace of its own. Pick an id no package uses, put the tree under it, and register it like any other file:

```json title="apps/web/src/locales/site/en.json"
{
  "site": {
    "home": { "title": "A home for your people" }
  }
}
```

```ts title="apps/web/src/locales/app.ts"
export const appMessages: AppMessagesMap = {
  en: { site: async () => await import('./site/en.json') },
  pl: { site: async () => await import('./site/pl.json') },
}
```

`vitnode i18n check` treats it like a package: your default-locale file is the source of truth, and every other language is checked against it for missing and leftover keys. No default-locale file at all is an error - there would be nothing to translate from.

---

## Translation Architecture [#translation-architecture]

| Source               | Role                                                        | Order                   |
| :------------------- | :---------------------------------------------------------- | :---------------------- |
| `@vitnode/core`      | Base strings for auth, admin shells, and dialogs            | Base layer              |
| **Plugins**          | Domain strings declared in `plugins/*/src/locales`          | Second layer            |
| **Host Application** | Your own languages and rewordings in `apps/web/src/locales` | Highest priority (wins) |

Missing keys automatically fall back to `defaultLocale` (`en`), preventing raw key paths from displaying in production.

---

## Localized URLs [#localized-urls]

Strings aren't the only thing you can translate. The same `i18n` block decides how public URLs look in each language: a prefix (`/pl/...`), a domain per language (`vitnode.pl`), and translated paths such as `/pl/odkrywaj` for `/discover`:

```ts title="apps/web/src/vitnode.config.ts"
i18n: {
  defaultLocale: 'en',
  // [!code ++:3]
  routePaths: {
    pl: { '/discover': '/odkrywaj' },
  },
},
```

[Localized URLs](/docs/dev/i18n/localized-urls) covers the rules, domains, redirects and SEO.

## Learn More [#learn-more]

# Localized URLs (/docs/dev/i18n/localized-urls)

Plugins declare their pages in English. Your app decides how each page is spelled in every other language. So `/discover` stays `/discover` for English readers and becomes `/pl/odkrywaj` for Polish ones. It's the same route, the same component and the same `<Link to="/discover">`, with a second spelling.

{/* Image prompt: Diagram of one route "/discover" in the center, with arrows to two public URLs "/discover" (English flag) and "/pl/odkrywaj" (Polish flag), and a small "rewrite" label on each arrow. Clean flat style, dark theme, 1600x700. */}

## Quick start [#quick-start]

### Find the English path [#find-the-english-path]

Every plugin documents the paths its pages answer to. Core's are `/discover`, `/search`, `/users/:nameCode`, `/login`, `/settings` and friends. Those English paths are the keys you translate. Your app's own routes work the same way.

</Step>
<Step>

### Translate it in `vitnode.config.ts` [#translate-it-in-vitnodeconfigts]

```ts title="apps/web/src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  i18n: {
    defaultLocale: 'en',
    locales: [
      { code: 'en', name: 'English' },
      { code: 'pl', name: 'Polski' },
    ],
    // [!code ++:8]
    routePaths: {
      pl: {
        '/blog/:slug': '/wpisy/:slug',
        '/discover': '/odkrywaj',
        '/search': '/szukaj',
        '/users/:nameCode': '/uzytkownicy/:nameCode',
      },
    },
    timeZone: 'UTC',
  },
})
```

This is the configuration this site runs on.

</Step>
<Step>

### Restart `dev` [#restart-dev]

Every link, redirect, canonical URL and sitemap line now uses the new spelling. You don't touch any route file.

</Step>
</Steps>

## One route, many spellings [#one-route-many-spellings]

A translation never creates a route. The router's URL rewrite does the work in both directions:

- **Coming in**, `/pl/odkrywaj` is read as the Polish version of `/discover`, so the route tree matches `/discover`.
- **Going out**, `<Link to="/discover">` renders `/pl/odkrywaj` for a Polish reader.

Route files, route IDs, lazy-loaded chunks and every `to="..."` in your code stay exactly as they were. See [Navigation](/docs/dev/routing/navigation) for how the rewrite fits around `Link`.

## Translation rules [#translation-rules]

- **Keys are English source paths** in VitNode syntax: `:param` for a parameter and a trailing `*` for a catch-all. They must be real routes in your app, or the build tells you which one you probably meant.
- **Only static segments get translated.** A parameter keeps its value: `jane-1` stays `jane-1` in `/pl/uzytkownicy/jane-1`.
- **Parameters must match exactly.** You can't drop one, add one or rename one (`:nameCode` stays `:nameCode`). A `*` catch-all has to stay the last segment.
- **Lowercase only.** Non-ASCII letters are fine and get percent-encoded: `'/files': '/załączniki'` goes out as `/pl/za%C5%82%C4%85czniki`, and the browser shows `załączniki`.
- **Don't start with a locale code.** `/pl/...` or `/en/...` as the first segment would be read as a language prefix.
- **`/` can't be translated.** The home page is spelled by `localePrefix`.
- **`/admin` and `/api` are never localized.** They carry no prefix and no translation.
- **A missing translation falls back to English.** `/login` without an entry is `/pl/login`, so a half-translated app still works.

### Nested layouts [#nested-layouts]

A layout's children live under its URL, so if you translate a layout you have to translate everything inside it too. Core's settings area is a layout with two child pages:

```ts title="apps/web/src/vitnode.config.ts"
routePaths: {
  pl: {
    '/settings': '/ustawienia',
    '/settings/security': '/ustawienia/bezpieczenstwo',
    '/settings/devices': '/ustawienia/urzadzenia',
  },
},
```

If you leave out a child, the build fails with `inconsistent-layout-path` and suggests the missing line.

### Static siblings of a translated parameter [#static-siblings-of-a-translated-parameter]

Suppose a custom plugin (a made-up example, not a shipped one) has `/articles/:id` and `/articles/new`. If you translate only `/articles/:id` to `/artykuly/:id`, then `/articles/new` would also match that pattern and turn into `/artykuly/new` by accident. The build stops with `route-shadowed`. Translate the sibling too, or add an identity entry to keep it English:

```ts
routePaths: {
  pl: {
    '/articles/:id': '/artykuly/:id',
    '/articles/new': '/articles/new', // [!code ++]
  },
},
```

## Which language a request gets [#which-language-a-request-gets]

For a **public page**, the URL decides, in this order:

1. A configured **domain** (`vitnode.pl` is Polish). A prefix for a language that lives on another domain redirects there.
2. The **URL prefix** (`/pl/...`), under `always` or `as-needed`.
3. The **host's default locale**: the domain's `defaultLocale`, or `i18n.defaultLocale`.

Your saved preference (the `vitnode_locale` cookie) and `Accept-Language` **never** choose the language of a public page. One URL means one language, and that's what lets a CDN cache it, a crawler index it and a friend open the same page you shared. So a Polish domain never renders English because your browser remembers English.

Paths with no locale in them, `/admin` and `/api`, use the saved preference instead: the cookie first, then `Accept-Language`, then the host's default. The cookie is written when you switch language with the language switcher (on the same domain) or open a prefixed page such as `/pl/odkrywaj`, so the AdminCP follows the language you last asked for.

## `localePrefix` modes [#localeprefix-modes]

## A domain per language [#a-domain-per-language]

Give each language its own domain with `i18n.domains`:

```ts title="apps/web/src/vitnode.config.ts"
i18n: {
  defaultLocale: 'en',
  locales: [
    { code: 'en', name: 'English' },
    { code: 'pl', name: 'Polski' },
  ],
  // [!code ++:4]
  domains: [
    { origin: 'https://vitnode.com', defaultLocale: 'en' },
    { origin: 'https://vitnode.pl', defaultLocale: 'pl' },
  ],
  routePaths: {
    pl: { '/discover': '/odkrywaj' },
  },
},
```

Now `https://vitnode.pl/odkrywaj` is the Polish Discover page. A domain can also serve several languages with prefixes, using `locales: ['pl', 'cs']` plus `defaultLocale: 'pl'` under `as-needed` or `always`.

The rules:

- `origin` is a scheme and a host only: `https://vitnode.pl`, with no path, query or trailing page.
- Each host appears once, and each locale belongs to exactly one domain.
- Once you add `domains`, every enabled locale needs one, so a link to any language knows which host to open.
- Only **configured** hosts pick a locale or show up in SEO URLs, and a cross-domain redirect only goes to one of them.
- **Unconfigured hosts** (`localhost`, preview deployments) act as if there were no domains in the prefix modes. So `pnpm dev` keeps serving `/pl/odkrywaj` locally instead of bouncing you to production.

### Behind a proxy [#behind-a-proxy]

VitNode reads the host from the request URL your server hands it, which comes from the `Host` header. It **ignores `X-Forwarded-Host`**. Any visitor can send that header, and a proxy that doesn't overwrite it passes it straight through. If VitNode trusted it, a request to `vitnode.com` could render Polish, while the browser (which only knows its own address bar) hydrates English and gets different links. Worse, a cache that ignores `Vary` could store the resulting redirect for everyone.

So the one proxy requirement is: **forward the original `Host`**.

- **Vercel** does this already, nothing to set.
- **Nginx**: keep `proxy_set_header Host $host;`, as in the [self-hosted guide](/docs/dev/deployments/self-hosted#reverse-proxy-nginx-configuration).
- **Other proxies**: enable their "preserve host" option (Caddy does by default; Traefik: `passHostHeader`, on by default).

A proxy that rewrites `Host` to something like `localhost:3000` still works, but only as an unconfigured host, so every language is served there with its prefix and no domain picks a locale.

### Why `never` needs a domain per language [#why-never-needs-a-domain-per-language]

Without a prefix or a domain, `/discover` could be English for one visitor and Polish for the next, depending on a cookie. That's one URL with two languages: a CDN can't cache it, a crawler indexes whichever it saw first, and a shared link opens in the wrong language. So VitNode decides it for you: `localePrefix: 'never'` needs **one locale per host**. With several locales and no `domains`, the app stops with `ambiguous-never-prefix`. On an unconfigured host (like `localhost`), `never` serves only the default locale.

## Redirects to the canonical URL [#redirects-to-the-canonical-url]

Every non-canonical URL answers with a **308** to the canonical one, with the query string and hash kept intact. A redirect always lands on a URL that doesn't redirect again, so there are no loops.

Adding a translation doesn't break links people already shared: the old English spelling keeps working and redirects to the new one.

## Switching languages [#switching-languages]

The language switcher keeps you on the same page, with the same parameters, query and hash. `/pl/uzytkownicy/jane-1` switches to `/users/jane-1`.

Pages whose record has a different slug per language (see [below](#translated-segments-vs-localized-slugs)) declare their alternates, and the switcher follows them to the other language's own slug. If the language you pick isn't among the declared alternates, because that translation isn't published, you land on that language's home page instead of a 404. Switching to a language on another domain is a full page load.

## hreflang and canonical links [#hreflang-and-canonical-links]

A plugin page declares its alternates from `head()`, as **internal** paths: the English route with each language's own values filled in. Only include translations that are actually published.

```tsx title="plugins/articles/src/pages/article-page.tsx"
export const route = definePluginRoute({
  load: async ({ params }) => await fetchArticle(params.slug),
  head: ({ loaderData }) => ({
    title: loaderData?.title,
    // [!code ++:4]
    alternates: {
      en: '/articles/hello-world',
      pl: '/articles/witaj-swiecie',
    },
  }),
})
```

VitNode turns that into a `canonical` link, one `alternate` per language and an `x-default` for the default locale, all absolute and spelled for each language: `https://vitnode.pl/artykuly/witaj-swiecie` with domains, or your `VITNODE_WEB_URL` plus `/pl/artykuly/witaj-swiecie` without them.

<Callout type="warn" title="Internal paths, not public ones">
  Pass `/articles/witaj-swiecie`, not `/pl/artykuly/witaj-swiecie`. `alternates`
  are always read as internal paths, so a public one would be translated a
  second time. The delivery API gives you both: each alternate has a public
  `path` and an `internalPath`, and metadata has `canonicalInternalPath`.
</Callout>

A page backed by the Content System doesn't write any of this by hand. `@vitnode/core/tanstack/content` turns a delivery response into page data and a head. That covers redirects, 404s, the SEO title and description, and the internal alternates of every published translation. Blog's own post page is built this way:

```tsx title="plugins/blog/src/pages/post-page.tsx"
const loadBlogPost = async ({
  locale,
  slug,
}: {
  locale: string
  slug: string
}) => {
  const [resolution, detail] = await Promise.all([
    fetcher({
      plugin: '@vitnode/blog',
      method: 'get',
      module: 'content/blog',
      path: '/delivery/resolve/{slug}',
      args: { params: { slug: encodeURIComponent(slug) }, query: { locale } },
    }),
    fetcher({
      plugin: '@vitnode/blog',
      method: 'get',
      module: 'content/blog',
      path: '/{slug}',
      args: { params: { slug: encodeURIComponent(slug) }, query: { locale } },
    }),
  ])

return contentDeliveryPage({
    item: detail.status === 200 ? zodBlogPost.parse(await detail.json()) : null,
    resolution: await resolution.json(),
  })
}

export const route = definePluginRoute({
  load: async ({ context, params }) =>
    await loadBlogPost({ locale: context.locale, slug: params.slug }),
  head: ({ loaderData }) =>
    contentDeliveryPageHead(loaderData?.metadata, {
      title: loaderData?.item.title,
    }),
})
```

A retired slug answers with a 308 to the current one, and an unknown slug is a 404.

App routes can do the same with `pageHead` or `localeAlternateLinks` from `@vitnode/core/tanstack/metadata`:

```tsx title="apps/web/src/routes/pricing.tsx"
import { localeAlternateLinks } from '@vitnode/core/tanstack/metadata'

export const Route = createFileRoute('/pricing')({
  head: ({ match }) => ({
    links: localeAlternateLinks({
      internalPathname: '/pricing',
      locale: match.context.locale,
    }),
  }),
})
```

`internalPathname` means "the same page in every locale". Pass `alternates: { en: '...', pl: '...' }` instead when the path differs per language.

## Translated segments vs localized slugs [#translated-segments-vs-localized-slugs]

Two different things change in a URL, and they're owned by different people:

Put together, Blog's `/blog/hello-world` in English is `/pl/wpisy/witaj-swiecie` in Polish. The translation table never touches `witaj-swiecie`, and the content never touches `wpisy`.

## Content, sitemaps and search follow along [#content-sitemaps-and-search-follow-along]

Content Engine builds every URL with the same rules as the router, so nothing drifts:

- Canonical URLs, hreflang, `x-default`, sitemap lines, preview links and slug-history redirects all use your `localePrefix`, `domains` and `routePaths`.
- Only published translations become alternates. A Polish request that falls back to English content keeps the **English** canonical URL, so fallback text is never labelled as Polish.
- Slug-history redirects stay within their language.
- Search result URLs are built from `search.pathTemplate` (like `/blog/{slug}`) the same way, and they're absolute once domains are configured.

### Content URLs need a page [#content-urls-need-a-page]

A content type publishes URLs from `delivery.path` (default `/{publicApi.path}/:slug`) and `search.pathTemplate`. Both are English route paths, and **a page route has to serve them**. Otherwise every canonical link, sitemap line and search result would be a 404. So the build checks it: a content type whose URL no page route serves stops `dev` and `build` with `content-url-without-page`. Blog serves `/blog/:slug` with its own page, which is also why `'/blog/:slug'` is a valid `routePaths` key.

The web build can't read your API: `config.api.ts` is server code, and a plugin factory may need options only your app knows. So a plugin states its public content types **once**, in a browser-safe module exposed as `./content`, and both sides load that same module:

```ts title="plugins/blog/src/content.ts"
import { blogCategoryContentType } from '@/content/category'
import { blogPostContentType } from '@/content/post'

export const contentTypes = [blogPostContentType, blogCategoryContentType]
```

Any output layout works, as long as the package's `exports` resolve `@vitnode/<plugin>/content` (the `./*` wildcard in VitNode's own plugins covers it).

- **The web build** imports every configured plugin's `./content` module, checks each URL in it against your page routes (`content-url-without-page`), and writes the modules it loaded to `src/content-modules.gen.ts`.
- **The API**, when it boots, loads the same module and compares it with what the plugin actually registers, through admin and public modules alike. A plugin that publishes URLs without a loadable `./content` module stops the API with `content-module-missing`. One whose module leaves a published type out, or declares it with a different URL, stops it with `incomplete-content-types`.

Where the API looks depends on how the app is built:

| Setup                                       | The API checks against                                                                     | Wiring                                                                |
| :------------------------------------------ | :----------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| Single app (web and API in one)             | `src/content-modules.gen.ts`: exactly the modules this web build loaded and checked        | `buildApiConfig({ contentModules })`, already in `create-vitnode-app` |
| Separate API app (`apiMonorepo`, `onlyApi`) | `<plugin>/content` resolved from the API app's own `node_modules`, the same exports lookup | Nothing. Needs Node.js 22.12+ (synchronous `require` of an ES module) |

```ts title="src/vitnode.api.config.ts"
// [!code ++]
import { contentModules } from './content-modules.gen'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [blogApiPlugin()],
  // [!code ++]
  contentModules,
  // ...
})
```

<Callout type="warn" title="What a separate API can't prove">
  A separately built API proves that each plugin's `./content` module exists and
  matches what it publishes, which is what any web build would load. It can't
  prove that your web app configures that plugin, or was built from the same
  version. A plugin installed only in the API (a headless setup) has its URLs
  checked against no pages.
</Callout>

A plugin whose content publishes no URLs (no delivery, no search) needs none of this.

Details live in [Content Delivery and SEO](/docs/content-engine/public-pages) and [Search](/docs/dev/search).

<Callout type="info" title="Rebuild the search index after URL changes">
  Search stores each result's URL when it indexes it. After you change
  `routePaths`, `domains` or `localePrefix`, rebuild the index in **Core →
  Advanced → Search** so old results pick up the new URLs.
</Callout>

## Validation errors [#validation-errors]

A bad configuration fails loudly, when `dev` or `build` starts, not quietly in production. Every message starts with `[VitNode i18n]` and names the exact entry. The error is a `LocaleRoutingConfigError` with a `code`.

**Checked from the config alone** (web app and API):

**Checked at build time**, once the route list is known:

**Content URLs**, also at build time. These start with `[VitNode content URLs]` and are a `ContentUrlError`:

| Code                           | Cause                                                                                  | Fix                                                                            |
| :----------------------------- | :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `content-url-without-page`     | A content type's `delivery.path` or `search.pathTemplate` has no page route serving it | Add a page at that path, point the setting at an existing page, or turn it off |
| `invalid-content-types-module` | A plugin's `content` module doesn't export a `contentTypes` array                      | Export the plugin's `defineContentType` definitions, or delete the module      |

**Content declarations**, when the API boots (`VitNodeAPI`), also a `ContentUrlError`:

| Code                           | Cause                                                                                           | Fix                                                                                    |
| :----------------------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |
| `content-module-missing`       | The plugin publishes content URLs, but its `./content` module wasn't found where the API looked | Export the content types from a browser-safe module and expose it as `./content`       |
| `incomplete-content-types`     | The loaded module leaves a published content type out, or declares it with a different URL      | Add it to that module's `contentTypes`, and register those same definitions in the API |
| `invalid-content-types-module` | The module doesn't export a `contentTypes` array, or (separate API) Node.js can't `require` it  | Export the array; run Node.js 22.12+ and keep top-level `await` out of the module      |

## Migration notes [#migration-notes]

<Callout
  type="warn"
  title="`localePrefix: 'never'` on one host is now an error"
>
  If you ran `never` with several languages on one host and let a cookie pick
  the language, the app now stops with `ambiguous-never-prefix`. Either add
  `domains` with one locale each, or switch to `localePrefix: 'as-needed'` so
  Polish lives at `/pl/...`. Old unprefixed links keep serving the default
  language.
</Callout>

- **`search.pathTemplate` no longer needs `{locale}`.** Write `/blog/{slug}`. A legacy leading `/{locale}/` is still accepted and stripped. `{locale}` anywhere else is an error. Then rebuild the search index.
- **Content URLs in the default locale are unprefixed** under `as-needed`. Canonical URLs, hreflang and sitemaps used to emit `/en/...` for every record, and now emit `/...`. Old `/en/...` links redirect with a 308.
- **Every content URL needs a page, and every plugin with public content ships a `./content` module.** A plugin that registers content types with delivery or search must export them as `contentTypes` from a browser-safe module exposed as `./content`. Until it does, the API refuses to boot with `content-module-missing`, which names each content type and URL. That's deliberate: the alternative is a site publishing links nobody checked. Every URL in that module then needs a page route (`content-url-without-page`). Blog now ships its `/blog/:slug` page. Plugins without public content are unaffected.
- **Single apps pass `contentModules`.** Add `import { contentModules } from './content-modules.gen'` and `contentModules` to `buildApiConfig` in `src/vitnode.api.config.ts`. The file is generated by `dev` and `build`. Without it the API falls back to resolving packages at runtime, which a bundled production server can't do.
- **A split API needs the same routing config.** In a single app, `vitnode.api.config.ts` reuses `vitNodeConfig.i18n`, so nothing to do. In a separate API app (`apiMonorepo` or `onlyApi` in `create-vitnode-app`), its own `i18n` must mirror `localePrefix`, `domains` and `routePaths`. Otherwise canonical URLs, sitemaps and search links built by the API won't match the site.

```ts title="apps/api/src/i18n.ts"
export const i18n = {
  defaultLocale: 'en',
  locales: [
    { code: 'en', name: 'English' },
    { code: 'pl', name: 'Polski' },
  ],
  // [!code ++:6]
  localePrefix: 'as-needed',
  routePaths: {
    pl: {
      '/discover': '/odkrywaj',
    },
  },
  timeZone: 'UTC',
  messages: {},
} satisfies VitNodeI18nConfig
```

## Learn More [#learn-more]

# Messages & ICU Syntax (/docs/dev/i18n/messages)

VitNode localizes strings using standard ICU MessageFormat, parsed and rendered through [`use-intl`](https://use-intl.dev).

## Quick start [#quick-start]

### 1. Define Message Strings [#1-define-message-strings]

```json title="plugins/blog/src/locales/en.json"
{
  "@vitnode/blog": {
    "welcome": "Welcome back, {name}!",
    "articles_count": "{count, plural, =0 {No articles} one {1 article} other {# articles}}",
    "terms_notice": "By clicking continue, you agree to our <link>Terms of Service</link>."
  }
}
```

---

### 2. Render in React Components [#2-render-in-react-components]

```tsx title="plugins/blog/src/views/blog-header.tsx"
import { useTranslations } from "use-intl"
import { Link } from "@tanstack/react-router"

export const BlogHeader = ({ count, name }: { count: number; name: string }) => {
  const t = useTranslations("@vitnode/blog")

return (
    <header className="flex flex-col gap-2">
      <h1>{t("welcome", { name })}</h1>
      <p>{t("articles_count", { count })}</p>

{/* Rich text with custom tags */}
      <small className="text-muted-foreground">
        {t.rich("terms_notice", {
          link: (chunks) => <Link to="/terms" className="underline">{chunks}</Link>,
        })}
      </small>
    </header>
  )
}
```

---

## ICU Syntax Reference [#icu-syntax-reference]

### 1. Variables & Numbers [#1-variables--numbers]

```json
{
  "price": "Total: {amount, number, ::currency/USD}",
  "date": "Published on {date, date, medium}"
}
```

### 2. Cardinal Pluralization [#2-cardinal-pluralization]

```json
{
  "unread": "{count, plural, =0 {No unread messages} one {1 unread message} other {# unread messages}}"
}
```

### 3. Select / Enums [#3-select--enums]

```json
{
  "status": "{status, select, draft {Draft} published {Published} other {Archived}}"
}
```

---

## Where Message Files Live [#where-message-files-live]

| Folder | Audience | Purpose |
| :--- | :--- | :--- |
| `src/locales/{locale}.json` | **Frontend** | Browser UI, page text, and AdminCP navigation |
| `src/locales/api/{locale}.json` | **API Server** | Transactional emails and backend validation errors |

## Learn More [#learn-more]

# Namespaces (/docs/dev/i18n/namespaces)

A namespace is a dotted path into the merged message tree - `core.global`,
`@vitnode/blog.admin.article`. It is the unit of two things at once: what
`useTranslations` reads from, and what a page is allowed to download. The merged
tree holds every installed plugin's copy, and no page should ship all of it, so a
page names the branches it renders and gets exactly those.

## Example [#example]

```json title="plugins/my-plugin/src/locales/en.json"
{
  "my-plugin": {
    "home": { "title": "Hello World" },
    "admin": { "overview": { "title": "My plugin" } }
  }
}
```

```tsx
const t = useTranslations('my-plugin.home')
```

Two namespaces exist there - `my-plugin.home` and `my-plugin.admin.overview` -
and a page that renders the public one never downloads the admin one.

## The tree [#the-tree]

Everything sits under the id of the package that owns it. Core owns three
branches; a plugin owns exactly one, named after itself.

| Namespace         | Owner           | What is in it                                               |
| ----------------- | --------------- | ----------------------------------------------------------- |
| `core.global`     | core            | Design-system strings every VitNode page needs              |
| `core.*`          | core            | Auth, files, search, content - the public site              |
| `admin.*`         | core            | The AdminCP: `admin.global`, `admin.user`, `admin.staff`, … |
| `@vitnode/blog.*` | `@vitnode/blog` | Everything that plugin ships                                |
| `{your-plugin}.*` | your plugin     | Everything yours ships                                      |

`core.global` is special only in that it is provided above every route, so any
shared component can translate itself wherever it is mounted. Everything else is
asked for.

## The per-plugin prefix rule [#the-per-plugin-prefix-rule]

**Every top-level key a plugin ships is the plugin's own id.** A key outside it
collides with core and with every other plugin, so VitNode ignores it rather than
letting two packages fight over one path.

```json title="plugins/my-plugin/src/locales/en.json"
{
  "my-plugin": {
    "hello": "Hello World" // [!code ++]
  },
  "world": "World" // [!code --]
}
```

Scoped ids work exactly the same way - `@vitnode/blog` is one path segment even
though it contains a slash, so `@vitnode/blog.admin` is a legal two-segment
namespace.

<Callout title="Permission labels are the one exception" type="info">
  A staff permission's label is a **flat top-level key**, not a branch:
  `@vitnode/blog:posts:can_view`. There is nothing to slice a namespace out of,
  so the AdminCP asks for those keys as if they were namespaces and has to chunk
  the request to stay under the limit below. If you are writing them, see [Staff
  permissions](/docs/dev/working-with-users/staff-permissions).
</Callout>

## Asking for a namespace [#asking-for-a-namespace]

Declare the exact branches a plugin page renders as the route's `messages`.
VitNode loads them with the route chunk, so public pages do not download a
plugin’s AdminCP copy just because it exists.

```ts title="plugins/my-plugin/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/reports', {
    component: lazy(() => import('./pages/reports-page')),
    // [!code ++]
    messages: ['my-plugin.reports'],
  }),
])
```

A route inherits every namespace its layouts declare, so a shared frame can name
them once for a whole subtree. The route module then calls
`useTranslations('my-plugin.reports')`; if a key renders as its own name, confirm
the route declared the matching namespace.

## Limits [#limits]

A namespace list reaches the server through a server function, which is a public
`POST` endpoint once the app is built. So the rules are enforced rather than
assumed, and the same rules validate a plugin's build-time declaration - one
definition, in `@vitnode/core/routing`, so a route tree cannot accept something the
server refuses.

On top of the numbers: a namespace must be a non-empty string, must not contain
an empty segment (`core..global`, a leading or trailing dot), and must not
contain `__proto__`, `constructor` or `prototype` in any segment. All three are
rejected outright rather than filtered away - a namespace containing one is not a
namespace with a typo in it.

Import the constants if you need to budget against them:

```ts
import { MAX_NAMESPACES } from '@vitnode/core/tanstack/i18n'
```

## Gotchas [#gotchas]

<Callout title="Every string renders as its own key" type="error">
  The symptom of a namespace that was never asked for. Check that the route
  declares it in the plugin's `routes.ts`.
</Callout>

<Callout
  title="Over sixteen namespaces means chunking, not raising the cap"
  type="warn"
>
  `At most 16 namespaces may be requested.` is a thrown error, not a truncation.
  If you genuinely need more - a screen rendering one flat key per permission -
  split the request the way the staff screens do and merge the results, rather
  than reaching for a bigger number.
</Callout>

<Callout title="Namespaces are per route, not per plugin" type="info">
  Name what the page renders. Declaring your plugin's whole tree on every route
  puts your AdminCP copy in the bundle of a public page nobody logged in is
  looking at.
</Callout>

<Callout title="A pendingComponent renders above its own provider" type="warn">
  A layout route's `pendingComponent` renders *in place of* the layout, so it is
  outside the `RouteMessages` that layout mounts. Either keep it free of
  translated text or mount a provider inside it. A child route's
  `pendingComponent` is fine - it renders into the layout's `<Outlet />
  `, which only exists once the provider has.
</Callout>

## Next [#next]

# Translating Pages (/docs/dev/i18n/pages)

VitNode uses [`use-intl`](https://use-intl.dev) for frontend translations. To keep initial payloads small, pages only download the translation namespaces they explicitly declare.

## Quick start [#quick-start]

### 1. In a Plugin Route (Recommended) [#1-in-a-plugin-route-recommended]

Plugin routes declare their namespaces as `messages` in `routes.ts`. VitNode loads the strings in parallel with the route chunk automatically:

```ts title="plugins/blog/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/blog/about', {
    component: lazy(() => import('./pages/about-page')),
    messages: ['@vitnode/blog.about'], // [!code ++]
  }),
])
```

Read strings directly with `useTranslations`:

```tsx title="plugins/blog/src/pages/about-page.tsx"
import { useTranslations } from 'use-intl'

const AboutPage = () => {
  const t = useTranslations('@vitnode/blog.about')

return <h1>{t('title')}</h1>
}

export default AboutPage
```

And define the messages in `plugins/blog/src/locales/en.json`:

```json title="plugins/blog/src/locales/en.json"
{
  "@vitnode/blog": {
    "about": {
      "title": "About Our Blog"
    }
  }
}
```

<Callout type="idea" title="Keep feature copy in the plugin">
  Host messages are for the site shell. A product page should declare its plugin
  namespace as the route's `messages` and keep its locale JSON beside the route.
</Callout>

## Placeholders and Pluralization [#placeholders-and-pluralization]

VitNode supports ICU message syntax out of the box:

```json title="plugins/blog/src/locales/en.json"
{
  "cart": {
    "greeting": "Hello, {name}!",
    "items": "{count, plural, =0 {No items} one {1 item} other {# items}}"
  }
}
```

In your React component:

```tsx
const t = useTranslations('cart')

return (
  <div>
    <p>{t('greeting', { name: 'Alex' })}</p>
    <p>{t('items', { count: 3 })}</p>
  </div>
)
```

<Callout type="info" title="Global namespaces">
  `core.global` is provided by the root shell to every route, supplying shared
  strings for dialogs, toasts, and buttons.
</Callout>

## Learn More [#learn-more]

# API i18n (/docs/dev/i18n/server)

The API gets the same message tree the frontend does, reachable in any route as `c.get("i18n")`.

```ts
const t = await c.get('i18n').getTranslator()

return c.json({ message: t('core.global.save') })
```

<Callout title="Nothing is copied" type="info">
  The API reads locale files straight out of `node_modules`. There is no build
  step to remember and no `src/locales/` folder to keep in sync - install a
  plugin and its translations are available on the server immediately.
</Callout>

The server loads a different, smaller set of strings than the frontend. Packages ship two trees - the frontend's UI copy in `src/locales/`, and the server's strings (emails) in `src/locales/api/` - and the API only ever loads the second. An API-only app never pulls in the admin UI's messages.

## Which locale a request gets [#which-locale-a-request-gets]

`resolveLocale` walks four options in order and takes the first one your app actually lists in `i18n.locales`:

<Steps>

<Step>

### An explicit choice [#an-explicit-choice]

`getTranslator("pl")`, or the `locale` you passed to `email.send()`. Use it when the language is a property of the thing you are rendering rather than of the caller.

</Step>

<Step>

### The signed-in user's language [#the-signed-in-users-language]

`core_users.language`, already loaded on `c.get("user")`.

</Step>

<Step>

### The `Accept-Language` header [#the-accept-language-header]

Parsed with its `q` weights, matched exactly first and then on the primary subtag - so `pl-PL` still finds `pl`.

</Step>

<Step>

### `defaultLocale` [#defaultlocale]

`en` unless your `i18n` config says otherwise.

</Step>

</Steps>

Anything not in `i18n.locales` is skipped rather than used, so a stale language code on a user row cannot produce a half-English page.

### Rendering for someone else [#rendering-for-someone-else]

That chain describes the _caller_. When the language belongs to whoever you are rendering for rather than to whoever made the request - an email recipient, a queued job's target - reach for `resolveSupportedLocale` instead:

```ts
const locale = c.get('i18n').resolveSupportedLocale(recipient.language)
```

It takes the language you hand it when the app ships it and `defaultLocale` when it doesn't, and it never touches the request. Dropping a language from `i18n.locales` should send that user English, not the language of the admin who clicked the button.

## The API [#the-api]

<TypeTable
  type={{
    getTranslator: {
      description:
        'use-intl translator for the resolved locale. Pass a locale to override the resolution.',
      type: '(locale?: string) => Promise<Translator>',
    },
    getMessages: {
      description: 'The merged message tree, if you need the raw object.',
      type: '(locale?: string) => Promise<Messages>',
    },
    resolveLocale: {
      description:
        'Runs the resolution above for the caller, without loading anything.',
      type: '(explicit?: string) => string',
    },
    resolveSupportedLocale: {
      description:
        'A locale you already have, or defaultLocale if the app does not ship it. Never reads the request.',
      type: '(preferred?: string) => string',
    },
    locales: {
      description: 'Every locale the app accepts.',
      type: 'LocaleConfig[]',
    },
    defaultLocale: {
      description: 'The fallback locale.',
      type: 'string',
    },
  }}
/>

Merged trees are cached per locale for the life of the process, so only the first call per language touches the filesystem.

## Emails [#emails]

Emails run through `resolveSupportedLocale`, so they render in the recipient's language or `defaultLocale` - never in the sender's. You rarely call the translator yourself:

```ts title="src/api/modules/users/routes/welcome.route.ts"
await c.get("email").send({
  user, // `user.language` decides the locale
  subject: ({ i18n }) => createTranslator(i18n)("welcome.email.subject"),
  content: props => <WelcomeEmail {...props} />,
});
```

Sending to a bare address instead of a user? Pass `locale` explicitly:

```ts
await c.get("email").send({
  to: "hello@example.com",
  locale: "pl", // [!code highlight]
  subject: "Cześć",
  content: props => <WelcomeEmail {...props} />,
});
```

The template receives `i18n` as a prop and turns it into a translator with `createTranslator` from `use-intl`:

```tsx title="src/emails/welcome.tsx"
import { createTranslator } from 'use-intl' // [!code ++]

export default function WelcomeEmail({ i18n }: DefaultTemplateEmailProps) {
  const t = createTranslator(i18n)

return <Text>{t('welcome.email.body')}</Text>
}
```

## Shipping translations with a plugin [#shipping-translations-with-a-plugin]

A plugin owns its languages, and it splits them the same way the framework does: frontend strings in `src/locales/`, server strings (emails) in `src/locales/api/`. Each tree gets a barrel and is registered with the matching config - the frontend tree with `buildPlugin` in `config.tsx`, the server tree with `buildApiPlugin` in `config.api.ts`.

Most plugins render nothing server-side, so they ship only the frontend tree. That one is registered twice, and the two halves are not interchangeable:

```ts title="plugins/{your_plugin}/src/config.tsx"
import messages from './locales'

export const yourPlugin = () =>
  buildPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    localeFiles: {
      // [!code ++:2]
      en: '@acme/your-plugin/locales/en.json',
    },
    messages,
  })
```

`messages` is your own barrel, whose `import('./en.json')` is relative to your build output - right for anything running inside your package, and a specifier no host bundler can follow. `localeFiles` is the same list written as the subpaths your `package.json` exports, and it is what an app's translations are actually loaded from: the app's build turns it into literal imports in `src/package-messages.gen.ts`. Ship both, and keep them in step.

Add the `api/` tree only when your plugin sends email:

```ts title="plugins/{your_plugin}/src/locales/api/index.ts"
import type { LocaleMessagesMap } from '@vitnode/core/lib/i18n/types'

const messages: LocaleMessagesMap = {
  en: async () => await import('./en.json', { with: { type: 'json' } }),
}

export default messages
```

```ts title="plugins/{your_plugin}/src/config.api.ts"
import messages from './locales/api' // [!code ++]

export const yourApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    messages, // [!code ++]
    modules: [postsModule],
  })
```

Adding a language later is a new file plus one line in each list that names it - apps pick it up on their next install, and can translate your plugin without forking it by dropping a file in their own `src/locales/{your_plugin}/`.

## Typing the keys [#typing-the-keys]

`t()` autocompletes from a `global.d.ts` that augments use-intl's `Messages`. Import the tree an app actually uses: an API-only app types against the server tree alone, a frontend-only app against the frontend tree, and a single app - one that serves the frontend and runs the API together - against both.

```ts title="global.d.ts (single app)"
/// <reference types="use-intl" />

import coreApi from '@vitnode/core/locales/api/en.json' with { type: 'json' }
import core from '@vitnode/core/locales/en.json' with { type: 'json' }

declare module 'use-intl' {
  interface AppConfig {
    Messages: typeof core & typeof coreApi // [!code highlight]
  }
}
```

<Callout title="Keys must be namespaced" type="warn">
  Everything a plugin ships belongs under its own namespace, or it will collide
  with core. See [Namespaces](/docs/dev/i18n/namespaces).
</Callout>

## When a translation goes missing [#when-a-translation-goes-missing]

VitNode says so, once per package and locale, rather than quietly rendering raw keys:

```
[VitNode i18n] Could not load "pl" messages for "@vitnode/blog" - its strings will render as raw keys.
```

Run [`vitnode i18n check`](/docs/dev/i18n) to find gaps before your users do.

# Introduction (/docs/dev)

VitNode is a **TanStack Start** front end, a **Hono** API, Postgres, and an
AdminCP. Its important rule is pleasantly simple: product features live in
**plugins**. A plugin owns its pages, APIs, data, translations, and AdminCP
extensions, so your host app does not become a drawer full of mystery cables.

{/* Image prompt: Clean dark-theme architecture diagram. A TanStack Start application and Hono API sit in the center, Postgres below, and three colorful plugin packages connect to routes, API modules, data, and AdminCP. Keep labels large and legible, 1600x900. */}

<Callout type="info" title="Canary documentation">
  These pages follow VitNode 2.0 on the `canary` branch. It moves quickly; when
  code and prose disagree, trust the code and send the prose a friendly PR.
</Callout>

## Start with a running app [#start-with-a-running-app]

<Cards>
  <Card
    icon={<RocketIcon />}
    title="Get an app running"
    description="Scaffold VitNode, migrate Postgres, and enter AdminCP."
    href="/docs/dev/setup"
  />
  <Card
    icon={<PackagePlusIcon />}
    title="Create a plugin"
    description="Make the package that will own your first feature."
    href="/docs/dev/plugins/create"
  />
  <Card
    icon={<ServerIcon />}
    title="Deploy VitNode"
    description="Build, migrate, and run your app on a server or container."
    href="/docs/dev/deployments/self-hosted"
  />
</Cards>

## Create an app [#create-an-app]

```bash tab="bun"
bun create vitnode-app@canary
```

```bash tab="pnpm"
pnpm create vitnode-app@canary
```

```bash tab="npm"
npm create vitnode-app@canary
```

</Tabs>

Choose **Single App** for one TanStack Start app with Hono at `/api`, or a
monorepo when web and API deploy separately. If you plan to create plugins,
enable **Turborepo** during setup: the generator needs a workspace root.

## The five-minute path [#the-five-minute-path]

1. Start Postgres (Docker is the low-drama local choice).
2. Run `db:migrate` to create core tables and your first administrator.
3. Run `dev`, then visit `http://localhost:3000/admin`.
4. Create a plugin for your first product page, API endpoint, content type, or
   dashboard widget.

Every command above is expanded in [Getting started](/docs/dev/setup). From
there, [Build your first plugin](/docs/guides/first-plugin) gives you a real
route to visit—not just a philosophical plugin.

## Find the right reference [#find-the-right-reference]

<Cards>
  <Card
    icon={<PackagePlusIcon />}
    title="Plugin routes"
    description="Claim public or AdminCP URLs without adding host route files."
    href="/docs/dev/routing"
  />
  <Card
    icon={<ServerIcon />}
    title="Admin Control Panel"
    description="Add plugin-owned screens, navigation, permissions, and widgets."
    href="/docs/dev/plugins/admin"
  />
  <Card
    icon={<BookOpenIcon />}
    title="Content Engine"
    description="Define content once and receive data, API, and AdminCP tools."
    href="/docs/content-engine"
  />
</Cards>

# Mobile Navigation (/docs/dev/mobile-navigation)

On a phone, the desktop header's navigation has nowhere to go. So below the
`sm` breakpoint (640px) VitNode splits it in two: your most-used links move to a
**floating bottom bar** pinned to the bottom of the screen - the kind your thumb
already knows from native apps - and everything else lives in a **side drawer**
behind the user button at the top.

Both are managed in the AdminCP, no code or config required.

{/* Image prompt: A phone-sized light-mode screenshot of a community site. At the bottom floats a white, fully rounded bar with a soft shadow and four equal tabs - "Home", "Discover", "Search" and a hamburger "Menu" tab, with icons above small labels, the active "Search" tab tinted blue on a light gray pill. Top right in the header sits a small round user avatar. Neutral grays, blue accent, 390x844. */}

## Two menus, one screen [#two-menus-one-screen]

Open **AdminCP → System → Navigation**. It has two tabs, named after where the
menu sits rather than the device, because a tablet is happy with the header:

Each tab works the same way: **Add link** opens the same picker (a page one of
your plugins provides, or a custom link), rows drag to reorder, and the row menu
has Edit, Move up, Move down and Remove. A page can sit in both menus at once -
Search in the header _and_ in the bottom bar is a perfectly normal choice.

Once the bottom bar holds three links, **Add link** switches off until you remove
one.

{/* Image prompt: A light-mode AdminCP screenshot of the Navigation page. Under the title, a segmented tab control reads "Header | Bottom bar" with "Bottom bar" selected and a hint beside it: "Up to three links at the bottom of the screen on phones, plus a Menu tab with the rest of the header menu." Below, one rounded card headed "3 of 3 links" lists Home, Discover and Search as compact rows with drag handles. The "Add link" button top right is disabled. Neutral grays, blue accent, 1440x900. */}

## The bottom bar [#the-bottom-bar]

Each link is an icon above a short label. The current page is tinted and sits
on a highlight that slides between tabs. A tab counts as current when the URL is
its address or anything below it, so `/blog/my-first-post` keeps a Blog tab lit
(`/` only matches the home page itself).

The last tab is always **Menu**. It opens a drawer from the bottom with the
rest of the Header menu - everything the bar does not already show, dropdowns
included. On a page that lives in there, the Menu tab is the one lit. If the bar
already covers every header link, the Menu tab steps aside.

An empty bottom bar is not drawn at all. That is the default on a fresh
install, so phones start with just the header and its side drawer until you add
a link.

<Callout type="info" title="Give every link an icon and a short label">
  At 320px each of the four tabs gets about 72px, which fits one word like
  "Discover" or "Settings" - longer labels are cut off with an ellipsis. A link
  without an icon shows the first letter of its label instead. Titles are per
  item, so the header can say "Community highlights" while the bottom bar says
  "Discover".
</Callout>

## The side drawer [#the-side-drawer]

The user button stays at the top of the header, where it always was. On a phone
it shows the member's avatar (or a person icon for guests), and a tap slides a
drawer in from the side with:

- the member's name and email, linking to their profile - or **Login** and
  **Register** buttons for guests,
- the **full Header menu**, dropdowns included - only while the bottom bar is
  empty, since otherwise its Menu tab already has it,
- the account links from the desktop user menu (profile, files, settings,
  AdminCP for admins),
- theme and language switches,
- **Log out**.

Swipe it away, tap outside it, press <kbd>Esc</kbd> or hit the close button.
Desktop is untouched: the same button still opens the usual dropdown there.

{/* Image prompt: A phone-sized dark-mode screenshot of a side drawer covering the right five-sixths of the screen over a blurred page. At the top "Menu" with a close X, then a rounded card with a round avatar, the name "Ada" and an email, a "Navigation" list with icons and the current item highlighted, an "Account" list (My Profile, My Files, Settings), and a Light / Dark / System segmented control. Neutral grays, blue accent, 390x844. */}

## For developers [#for-developers]

- **API.** Both menus live in `core_navigation`; a `location` column says which
  (`header` or `bottom_bar`). The admin routes under `admin/navigation` take an
  optional `location` on `/create` and `/reorder` and default to the header, so
  older clients keep working. The bottom bar refuses a parent (`400`) and a
  fourth link (`409`).
- **Public data.** The middleware response carries the bottom bar next to the
  header menu as a flat `bottomBar` array, cached separately and expired
  together with it.
- **Events.** `navigation.reordered` includes `location`. See
  [Built-in events](/docs/dev/events/built-in-events).
- **Room at the bottom.** While the bar is on screen, the page gets extra
  bottom padding so it never covers your footer.
- **Notches and home indicators.** The bar sits above the iPhone home indicator
  via `env(safe-area-inset-bottom)`, which needs `viewport-fit=cover` in your
  viewport meta tag. New apps have it; in an older app, update the viewport
  entry in `src/routes/__root.tsx`:

```ts title="src/routes/__root.tsx"
{ content: 'width=device-width, initial-scale=1, viewport-fit=cover', name: 'viewport' },
```

- **Translations.** The drawer's own words - "Menu", "Navigation", "Account" -
  live under `core.global.mobile_nav`; the AdminCP tab labels under
  `admin.navigation.tabs`. See [Languages & Localization](/docs/dev/i18n) to
  translate them.

# Configure moderators (/docs/dev/moderation/configure-moderators)

You set up moderators on the same AdminCP screen as every other staff permission. This guide makes a user a moderator who handles blog reports everywhere and example article reports only in some categories.

## Before you begin [#before-you-begin]

You need the `staff_moderators` admin permissions **Create moderators** and **Edit moderator permissions**, or a root role. The content types you want moderated must have [reports enabled](/docs/dev/moderation/enable-reports).

<Steps>

<Step>

### Add the moderator [#add-the-moderator]

Open **AdminCP → Staff → Moderators** and choose **Add Moderator**. Pick a role or a single user and save. The new entry grants nothing yet, and the AdminCP opens its permissions.

</Step>

<Step>

### Grant report permissions [#grant-report-permissions]

Keep **Restricted** selected. Pick a plugin on the left, open a module, and tick the permissions. For the blog, open **Articles** and tick **View article reports**, **Claim, assign and resolve article reports**, **Open hidden articles** and **Hide and unhide articles**.

A permission that depends on another one stays locked until its dependency is ticked. **Hide and unhide articles** needs **Open hidden articles**, so a moderator can always see what they hid.

</Step>

<Step>

### Choose where a scoped permission applies [#choose-where-a-scoped-permission-applies]

A scoped permission shows its scope under the checkbox: **All resources**, or the number of selected resources. Here the example plugin's **View reports** covers two categories and the management permission covers one:

Choose **Change** to open the picker. **All resources** includes resources created later. **Selected resources** lists the family's resources with a search box, loading more on demand:

Tick **Apply to every scoped permission in this module** to copy the same scope to the module's other scoped permissions. Each permission still saves its own scope, so you can narrow one afterwards.

</Step>

<Step>

### Save [#save]

Choose **Save changes**. The moderator's permissions apply on their next request. If a resource no longer exists, the picker marks it **Removed**. Take it out before saving.

</Step>

</Steps>

## Check the result [#check-the-result]

Sign in as the moderator. The user menu now has a **Moderator CP** link to `/modcp/reports`, and the reports board shows blog reports plus example article reports from the two selected categories only. See [Process reports](/docs/dev/moderation/process-reports).

## When saving is refused [#when-saving-is-refused]

The form checks scopes before it sends them, and the API checks them again. Each problem is shown under the permission it belongs to:

| Message                                                    | What to change                                                 |
| ---------------------------------------------------------- | -------------------------------------------------------------- |
| Choose where *permission* applies                          | Open **Change** and pick **All resources** or some resources   |
| Pick at least one resource for *permission*                | A selection cannot be empty                                    |
| *Permission* reaches further than *dependency*             | Narrow the permission, or widen its dependency first           |
| *Permission* names resources that no longer exist          | Remove the resources marked **Removed**                        |

You can only grant what you hold yourself. An administrator whose own moderator permissions cover two categories cannot give a third one, or **All resources**, to somebody else. Only a root administrator can grant **Unrestricted**. Changing a role's permissions or a user's roles takes effect immediately. VitNode clears the cached permissions of every affected user.

# Enable reports (/docs/dev/moderation/enable-reports)

Turn on reports for a content type so signed-in readers can flag a published record to your moderators. This guide follows the blog plugin, whose articles are reportable.

## Before you begin [#before-you-begin]

The content type needs a [public API](/docs/content-engine/public-api). A reader can only report what the public API lets them read, so a draft, a hidden record or an unpublished translation can never be reported.

<Steps>

<Step>

### Turn on reports [#turn-on-reports]

Add `reports: true` to the content type definition:

```ts title="plugins/blog/src/content/post.ts"
export const blogPostContentType = defineContentType({
  id: "blog.post",
  tableName: "blog_posts",
  publication: true,
  visibility: true,
  reports: true, // [!code ++]
  // ...
});
```

`reports` needs no migration. Reports live in core tables, and the content type's own tables do not change.

</Step>

<Step>

### Choose what the snapshot keeps (optional) [#choose-what-the-snapshot-keeps-optional]

By default, a report's snapshot keeps the record's title and its public `text`, `textarea`, `richText`, `enum` and `file` fields. The title comes from `admin.titleField` when that field is public. Pass an object to pick the fields yourself:

```ts title="plugins/blog/src/content/post.ts"
reports: {
  titleField: "title",
  snapshotFields: ["content", "excerpt"],
},
```

An unknown field, or a field of a kind a snapshot cannot hold, such as a relation, throws when the content type is defined. Fields you list explicitly may be private, because only moderators read snapshots.

</Step>

<Step>

### Label the generated permissions [#label-the-generated-permissions]

`reports: true` adds moderator permissions to the content type's permission module: `can_view_reports`, `can_manage_reports`, `can_edit_notes` and `can_delete_notes`, plus `can_view_hidden` and `can_hide` when the content type has [`visibility`](/docs/content-engine/content-visibility). Core ships generic labels, such as **View reports**. Override them in your plugin when you want your own wording:

```json title="plugins/blog/src/locales/en.json"
{
  "@vitnode/blog:posts:can_view_reports": "View article reports",
  "@vitnode/blog:posts:can_manage_reports": "Claim, assign and resolve article reports",
  "@vitnode/blog:posts:can_view_hidden": "Open hidden articles"
}
```

Enabling reports grants nothing. An administrator still has to give these permissions to a moderator. See [Configure moderators](/docs/dev/moderation/configure-moderators).

</Step>

<Step>

### Place the Report button [#place-the-report-button]

A plugin's own pages place the button themselves. Pass the record's stable id and the language the reader was served:

```tsx title="plugins/blog/src/pages/post-page.tsx"
import { ReportButton } from "@vitnode/core/tanstack/moderation";

{!metadata.hidden && metadata.itemId !== null ? (
  <ReportButton
    locale={metadata.locale}
    pluginId={CONFIG_PLUGIN.pluginId}
    requestedLocale={metadata.requestedLocale}
    targetId={metadata.itemId}
    targetType={blogPostContentType.id}
    typeLabel={t("report_type")}
  />
) : null}
```

The blog reads `itemId`, `locale` and `requestedLocale` from the [delivery resolution](/docs/content-engine/public-pages), so the button reports the article in the language the reader actually saw, even after a fallback. The form loads only when the dialog opens. A signed-out reader gets a **Sign in** link instead of the form.

</Step>

</Steps>

## Check the result [#check-the-result]

Rebuild with `pnpm build:plugins`, restart `pnpm dev`, sign in as a regular user and open a published article. Click **Report**, pick a reason and send it:

A toast says **Report sent**. Try sending it again and the toast tells you, politely, that you already did. A moderator with `can_view_reports` on the blog now sees the report in [the ModCP](/docs/dev/moderation/process-reports).

## What the server checks [#what-the-server-checks]

- The reporter must be signed in. A guest gets `401`.
- The target must be readable by the reporter through the public API. Anything else is `404`, the same answer as a typo.
- **Other** needs at least 10 characters of details. Details are at most 2000 characters.
- One reporter can hold one open report per target. Other reporters get their own reports.
- A user can file at most 20 reports per hour, on top of the per-IP [rate limiter](/docs/dev/advanced/rate-limiter) every API route has.

Reports work for targets outside the Content Engine too. A plugin registers its own target with `defineReportTarget`. See the [reference](/docs/dev/moderation/reference#custom-report-targets).

# Moderation (/docs/dev/moderation)

VitNode moderation lets signed-in users report content, and lets moderators review those reports and act on the content from the public site. It is built from three parts that core provides and any plugin can use: reports, the **Moderator CP** (ModCP) and scoped moderator permissions.

| Part                 | What it does                                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------------------------------- |
| Reports              | A report stores the reason, the reporter's details and a server-side snapshot of what the reporter saw          |
| Moderator CP         | `/modcp/reports` on the public site: a reports board, the snapshot, assignment, notes, resolution and content actions |
| Scoped permissions   | A moderator permission can cover every resource of a family, such as every forum section, or only some of them |

A moderator signs in with their normal user session. The ModCP never asks for an AdminCP session, and the server authorizes every ModCP request.

## Choose a guide [#choose-a-guide]

| You want to                                                     | Read                                                                |
| --------------------------------------------------------------- | ------------------------------------------------------------------- |
| Let readers report a Content Engine content type, like the blog | [Enable reports](/docs/dev/moderation/enable-reports)               |
| Limit moderators to some categories or sections                 | [Scoped permissions](/docs/dev/moderation/scoped-permissions)       |
| Give a user or role moderator permissions in the AdminCP        | [Configure moderators](/docs/dev/moderation/configure-moderators)   |
| Review, assign, resolve and act on reports                      | [Process reports](/docs/dev/moderation/process-reports)             |
| Look up routes, options, events and limits                      | [Moderation reference](/docs/dev/moderation/reference)              |

## How the parts fit together [#how-the-parts-fit-together]

1. A content type opts in with `reports: true`. This registers a **report target** and adds report permissions to the moderator catalog. Nobody holds them until an administrator grants them.
2. A reader clicks **Report** on the article page. The browser sends only the article id, the language, the reason and the details. The server checks that the reader can read the article, then stores a snapshot of it.
3. A moderator opens the ModCP. The reports board shows only reports the moderator may view, filtered before anything is counted.
4. The moderator takes the report, writes internal notes, hides the article if needed and closes the report with an outcome. Every step lands in the report's timeline.

Reports belong to core, not to the plugin. They keep their snapshot after the article is edited, after its revisions are pruned, after it is deleted and even after its plugin is uninstalled.

## What is not included yet [#what-is-not-included-yet]

This first version covers reports plus hiding and restoring content. It has no warnings, bans, approval queues, automatic moderation, anonymous reports, report notifications or permanent deletion from the ModCP. Moderators still have to read things themselves, sorry.

# Process reports (/docs/dev/moderation/process-reports)

The **Moderator CP** at `/modcp/reports` is where moderators work through reports, signed in with their normal account. This guide takes a spam report about a blog article from new to closed.

## Before you begin [#before-you-begin]

You need a moderator entry with `can_view_reports` for the content type, and `can_manage_reports` to change anything. Hiding needs `can_hide`. See [Configure moderators](/docs/dev/moderation/configure-moderators).

<Steps>

<Step>

### Open the board [#open-the-board]

Choose **Moderator CP** in the user menu. **Reports** is a board with three columns, **New**, **In progress** and **Done**. It holds the reports you may view, newest first in each column:

Search by title or report number above the board. Type at least three characters, like `#12` or `gift`. **Assigned** narrows the board to your reports or the unassigned ones.

Search and the filter live in the address, so you can send a filtered board to another moderator as a link. Each column loads 20 cards at a time, and **Show more** loads the next 20.

The pill next to the reason, like **+1**, means other people reported the same content. It only counts reports you may view. Reports outside your scopes never appear, not even in the column counts.

Drag a card to another column to move it, and the column tells you what will happen before you let go:

| Move | What happens |
| --- | --- |
| **New** → **In progress** | The report is assigned to you. |
| **In progress** → **New** | The assignee is removed. |
| Any column → **Done** | The close dialog opens, so you pick an outcome first. |
| **Done** → **New** or **In progress** | The reopen dialog asks for a reason. |

The card moves right away. If another moderator changed the report first, you get a message and the card slides back to where the server says it belongs. Cards always sit in date order, so a moved card lands where its date puts it, not where you dropped it.

On a touch screen, press and hold a card to pick it up. With a keyboard, focus the grip next to a card's **…** menu, press `Space`, use the arrow keys to pick a column and press `Space` again. The **…** menu has the same moves under **Move to**.

</Step>

<Step>

### Read the report [#read-the-report]

Open a report. The heading names the content type and its author. The main card starts with the **Description**, the reporter's own words, followed by the **Snapshot**, which is what the reporter saw at the moment they filed it. Choose **View full snapshot** to read it in a side panel. It never changes, even if the article was edited, its revisions were pruned or it was deleted.

On the right, **Details** opens with the reported content: its type, its title linked to the live page and the plugin it belongs to. Below are the assignee, the reporter and the author with their role colors, the reason and the **Visibility** of the content right now. **Linked reports** lists other reports about the same content, each with its reporter and the start of their text.

The snapshot names the language it was captured in. When the reader asked for another language and was served a fallback, it shows both. Files appear as names and sizes only. The report never copies the file itself.

</Step>

<Step>

### Take the report [#take-the-report]

Drag the card from **New** to **In progress**, or open the report and choose **Start progress** in the status button (**New**), or **Assign to me** under the assignee. The report is assigned to you and moves to **In progress**. To hand it over, open the assignee and pick another moderator; the list shows only moderators who may manage this report. **Stop progress** unassigns you and moves it back to **New**.

When two moderators take the same report at once, one wins and the other sees **Another moderator took this report first**. Every change carries the version you loaded, so acting on a stale page refreshes it instead of overwriting someone else's work.

</Step>

<Step>

### Note and act [#note-and-act]

Under **Activity**, choose **Add an internal note** or press `M`. Notes use the rich-text editor, and `Cmd+Enter` (`Ctrl+Enter` on Windows) saves them. They are visible to moderators only, never to the reporter or the author. **Notes** is the tab that opens first; **All** and **History** show the rest of the activity.

To change a note, open its **…** menu and choose **Edit** or **Delete**. You can always edit and delete your own notes. Editing or deleting another moderator's notes needs `can_edit_notes` or `can_delete_notes`. An edited note shows **(edited)**, and **History** records every edit with the text before and after, and every deletion with the removed text.

Open **Actions** next to the status button, choose **Hide content** and confirm. The article leaves the public site, search and the sitemap at once, exactly like [hiding it from the AdminCP](/docs/content-engine/content-visibility). It gets a revision, the `hidden` event fires and VitNode revalidates the caches. The activity records the action only when it succeeds. **Restore content** brings it back.

</Step>

<Step>

### Close the report [#close-the-report]

Drag the card to **Done**, or open the status button on the report and choose **Close report**. Pick an outcome, **No violation**, **Action taken** or **Duplicate**, and add an explanation for the other moderators if you like. When you already hid the content, **Action taken** is picked for you. **Close report** moves it to **Done**. Other reports about the same content stay open, because each reporter's report closes on its own.

On a closed report, the status button offers **Reopen**, which needs a reason that goes into the activity. Dragging the card out of **Done** asks for the same reason.

</Step>

</Steps>

## Check the result [#check-the-result]

The report sits in the **Done** column, and its activity lists the report, the assignment, your note, the hide and the resolution with names and times. Open the article signed out: it answers `404` while hidden. Open it as the moderator: it loads with the hidden notice, because `can_view_hidden` lets moderators inspect hidden content without any AdminCP edit permission.

## Who sees what [#who-sees-what]

- **Reporters** see only their own toast. Nothing about the report is public.
- **Moderators** with `can_view_reports` see the report, the reporter's name, the snapshot and the activity, for content in their scopes. Without it, a direct URL answers like a report that does not exist.
- **Moderators** with `can_manage_reports` can also take, reassign, note, resolve and reopen, and edit or delete their own notes.
- **Moderators** with `can_edit_notes` or `can_delete_notes` can edit or delete any moderator's notes.
- **Authors** of the reported content never learn who reported it.

When content moves to a resource outside a moderator's scope, the report moves with it. The moderator loses access, and if the report was assigned to them, VitNode unassigns it and logs that in the activity. When the content is deleted, the report keeps its last known scope.

# Moderation reference (/docs/dev/moderation/reference)

Exact names, types and behavior of the moderation APIs. For step-by-step guides, start at [Moderation](/docs/dev/moderation).

## `reports` on a content type [#reports-on-a-content-type]

`defineContentType({ reports })` from `@vitnode/core/content`. Omitted or `false` registers nothing.

| Name             | Type          | Required | Default                                                             | Description                                       |
| ---------------- | ------------- | -------- | ------------------------------------------------------------------- | ------------------------------------------------- |
| `titleField`     | field name    | No       | `admin.titleField` when it is in `publicApi.fields`, else none      | A `text`, `textarea` or `slug` field              |
| `snapshotFields` | field names   | No       | Public `text`, `textarea`, `richText`, `enum` and `file` fields, without the title | Fields of kind `text`, `textarea`, `richText`, `slug`, `number`, `boolean`, `enum`, `dateTime` or `file` |

`reports: true` uses both defaults. It throws without `publicApi`, for an unknown option, for `reports.enabled`, and for a field that does not exist or cannot be snapshotted.

The server-side model can scope reports with `createContentModel(definition, { moderationScope: { column, family } })`, where `column` is a base-table column holding the resource id.

## Generated moderator permissions [#generated-moderator-permissions]

Added to the content type's `permissionModule` in the **moderator** catalog, unless the plugin declares that moderator module itself. All of them carry the target's scope family when it has one.

| Permission           | Depends on         | Added when                   | Allows                                              |
| -------------------- | ------------------ | ---------------------------- | --------------------------------------------------- |
| `can_view_reports`   |                    | Always                       | The reports board, report details and related reports |
| `can_manage_reports` | `can_view_reports` | Always                       | Take, reassign, notes, resolve, reopen; edit and delete your own notes |
| `can_edit_notes`     | `can_manage_reports` | Always                     | Edit any moderator's notes                          |
| `can_delete_notes`   | `can_manage_reports` | Always                     | Delete any moderator's notes                        |
| `can_view_hidden`    |                    | The target can be hidden     | Opening hidden content on the public site           |
| `can_hide`           | `can_view_hidden`  | The target can be hidden     | **Hide content** and **Restore content** in the ModCP |

Content actions also need `can_manage_reports`, because they are recorded in the report.

## Scoped grants [#scoped-grants]

A stored grant is `{ plugin, module, permission, scope? }`. `scope` is one of:

```ts
{ family: "example.category", mode: "all" }
{ family: "example.category", mode: "selected", ids: ["1", "2"] }
```

Declare a scoped permission with `{ permission, dependsOn?, scope: "family.id" }` in `permissionStaff.moderator`. Admin permissions cannot be scoped. Resource ids match `/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/`.

`PATCH /api/@vitnode/core/admin/staff/entry/moderator/{id}` answers `400` with `{ error: "invalid_permissions", issues }`. Each issue has a `key` and a `type`: `missing_scope`, `empty_selection`, `invalid_resource`, `unknown_resource`, `unexpected_scope`, `wrong_family` or `dependency_scope`. A grant wider than the caller's own permissions is `403`.

`GET /api/@vitnode/core/users/permissions` returns the signed-in user's moderator grants, each with its `scope`.

## `defineModerationScope` [#definemoderationscope]

From `@vitnode/core/api/moderation`. Register with `buildApiPlugin({ moderation: { scopes } })`.

| Name          | Type                                                                              | Required | Description                                       |
| ------------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------- |
| `id`          | `string`                                                                          | Yes      | Lowercase and dot separated, unique across plugins |
| `label`       | `string`                                                                          | Yes      | i18n key                                          |
| `description` | `string`                                                                          | No       | i18n key shown in the picker                      |
| `list`        | `(c, { cursor, limit, search }) => Promise<{ items, nextCursor }>`                | Yes      | One page of resources for the AdminCP picker      |
| `find`        | `(c, ids) => Promise<items>`                                                      | Yes      | The resources with these ids that exist           |

An item is `{ id: string; label: string; context?: string[] }`. The AdminCP reads them through `GET /api/@vitnode/core/admin/staff/scope-resources/{family}?search=&cursor=`, or `?ids=1,2` to label a saved selection, which also returns `missing` ids.

## Custom report targets [#custom-report-targets]

Content Engine types register their target automatically. Anything else registers one with `defineReportTarget` and `buildApiPlugin({ moderation: { reportTargets } })`.

| Name               | Type                                                                | Required | Description                                                                 |
| ------------------ | ------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- |
| `type`             | `string`                                                            | Yes      | Stable id stored in reports, such as `forum.topic`                          |
| `label`            | `string`                                                            | Yes      | i18n key for the kind of thing, an ICU plural called with `count: 1`        |
| `permissionModule` | `string`                                                            | Yes      | Moderator module the report permissions are added to                        |
| `parseId`          | `(value) => string \| null`                                         | Yes      | Validates a client id before anything reads it                              |
| `capture`          | `(c, { targetId, locale }) => Promise<capture \| null>`             | Yes      | The snapshot body, or `null` when the reporter cannot read the target       |
| `current`          | `(c, { targetId, locale }) => Promise<{ hidden, url } \| null>`     | Yes      | The target now, or `null` once deleted                                      |
| `scope`            | `string`                                                            | No       | Scope family id                                                             |
| `resolveScope`     | `(c, targetId) => Promise<string \| undefined>`                     | With `scope` | The resource id now, `""` for none, `undefined` once deleted            |
| `actions`          | `{ hide?, unhide? }`                                                | No       | `{ permission, available(state), run(c, { actorUserId, targetId, tx }) }`    |

`run` executes inside the report's transaction and returns `{ changed, effects }`. `effects` runs after the commit. When `run` throws, the transaction rolls back and no timeline entry is written.

## Report lifecycle [#report-lifecycle]

| Status        | Reached by                                         |
| ------------- | -------------------------------------------------- |
| `new`         | Filing a report, unassigning, or reopening an unassigned report |
| `in_progress` | Taking or assigning a report, or reopening an assigned one |
| `done`        | Resolving with `no_violation`, `action_taken` or `duplicate` |

Reasons are `spam`, `abusive`, `rule_violation` and `other`; `other` needs details. Every change except a note needs `expectedVersion`. A stale version answers `409` with `{ error: "conflict", current }`, and taking a report someone else holds answers `409 already_claimed`.

## ModCP API routes [#modcp-api-routes]

All under `/api/@vitnode/core/moderation`, using the user session. A guest gets `401`, a user without a moderator entry `403`, and a report outside the moderator's scopes `404`.

| Method and path                      | Permission           | Body                                         |
| ------------------------------------ | -------------------- | -------------------------------------------- |
| `POST /reports`                      | Signed in            | `{ pluginId, targetType, targetId, locale?, requestedLocale?, reason, description? }` |
| `GET /reports`                       | `can_view_reports`   | Query `status`, `assigned`, `search`, `page`, `pageSize` |
| `GET /reports/{id}`                  | `can_view_reports`   |                                              |
| `POST /reports/{id}/claim`           | `can_manage_reports` | `{ expectedVersion }`                        |
| `POST /reports/{id}/assign`          | `can_manage_reports` | `{ expectedVersion, assigneeId }`            |
| `POST /reports/{id}/notes`           | `can_manage_reports` | `{ body }`: plain text or a rich-text document |
| `POST /reports/{id}/notes/{noteId}/edit` | `can_manage_reports` and the note's author, or `can_edit_notes` | `{ body }` |
| `POST /reports/{id}/notes/{noteId}/delete` | `can_manage_reports` and the note's author, or `can_delete_notes` | |
| `POST /reports/{id}/resolve`         | `can_manage_reports` | `{ expectedVersion, resolution, explanation? }` |
| `POST /reports/{id}/reopen`          | `can_manage_reports` | `{ expectedVersion, reason }`                |
| `POST /reports/{id}/actions/{action}` | `can_manage_reports` and the action's permission | `{ expectedVersion }` |
| `GET /reports/{id}/assignees`        | `can_manage_reports` |                                              |

## Events [#events]

| Event                         | Payload                                                       |
| ----------------------------- | ------------------------------------------------------------- |
| `moderation.report.created`   | `{ reportId, pluginId, targetType, targetId, reason }`        |
| `moderation.report.assigned`  | `{ reportId, assigneeId, previousAssigneeId }`                |
| `moderation.report.action`    | `{ reportId, action, pluginId, targetType, targetId }`        |
| `moderation.report.resolved`  | `{ reportId, resolution }`                                    |
| `moderation.report.reopened`  | `{ reportId }`                                                |
| `moderation.report.note_updated` | `{ reportId, noteId }`                                     |
| `moderation.report.note_deleted` | `{ reportId, noteId }`                                     |

Adding a note emits no event. Hiding through a report also emits the content type's own `hidden` or `unhidden` event. See [Built-in events](/docs/dev/events/built-in-events#moderation-events).

## Snapshot format [#snapshot-format]

Stored in `core_moderation_reports.snapshot` as JSON, `version: 1`:

| Field       | Description                                                            |
| ----------- | ---------------------------------------------------------------------- |
| `capturedAt` | When the server captured it                                          |
| `target`    | `{ pluginId, type, id }`                                               |
| `title`     | The display title                                                      |
| `fields`    | `{ name, label, kind, value }` with `kind` `text`, `richText`, `file` or `value` |
| `locale`    | `{ requested, served, fallback }`                                      |
| `source`    | `{ version, updatedAt, publishedAt }` of the captured state            |
| `authors`   | `{ id, name }` of the record's authors                                 |
| `scope`     | The scope resource at capture time, as evidence                        |
| `url`       | The public address at capture time                                     |
| `truncated` | `true` when text was cut to fit                                        |

The snapshot is read in one read-only transaction, so its fields and `source` describe the same state. The ModCP renders every snapshot with a generic viewer that needs no plugin code, and rich text goes through the same element allowlist as the public site.

## Limits [#limits]

| Limit                            | Value      |
| -------------------------------- | ---------- |
| Report details                   | 2000 characters, at least 10 for `other` |
| Plain-text notes, reopen reasons | 3 to 2000 characters |
| Resolution explanations          | Optional, up to 2000 characters |
| Rich-text notes                  | 64 KB, not empty |
| One text value in a snapshot     | 20,000 characters |
| Whole snapshot                   | 256 KB; rich text falls back to plain text, then fields are dropped |
| Reports per user                 | 20 per hour |
| Open reports per reporter and target | 1 |
| Queue page size                  | 25 by default, up to 100 |

File fields keep `{ id, name, mimeType, size, url }` only. The file's bytes are never copied, so a file deleted later cannot be opened from the report.

## Database [#database]

The migration `20261011193321_add_moderation_reports` adds `core_moderation_reports` and `core_moderation_report_events`. Neither references the reported content, so deleting content keeps its reports. Reporter, assignee and resolver are `ON DELETE SET NULL`, so deleting an account keeps the evidence. The unique `openKey` column enforces one open report per reporter and target, even under concurrent submissions.

# Scoped moderator permissions (/docs/dev/moderation/scoped-permissions)

A scoped moderator permission applies to every resource of a **scope family**, or only to the resources an administrator picks. "View reports in every section" and "hide topics only in section B" are two grants of scoped permissions. This guide uses the example plugin, whose article reports are scoped by category.

## Before you begin [#before-you-begin]

Scopes build on [staff permissions](/docs/dev/working-with-users/staff-permissions) and on reports. If your content type does not report yet, start with [Enable reports](/docs/dev/moderation/enable-reports).

<Steps>

<Step>

### Register a scope family [#register-a-scope-family]

A scope family tells the AdminCP which resources exist. Create it on the server with `defineModerationScope`:

```ts title="plugins/example/src/api/lib/moderation.ts"
import { defineModerationScope } from "@vitnode/core/api/moderation";
import { and, asc, gt, ilike, inArray } from "drizzle-orm";

import { example_categories } from "@/database/categories";

export const exampleCategoryScope = defineModerationScope({
  id: "example.category",
  label: "@vitnode/example.moderation.category.label",
  description: "@vitnode/example.moderation.category.desc",
  list: async (c, { cursor, limit, search }) => {
    const rows = await c
      .get("db")
      .select({ id: example_categories.id, name: example_categories.name })
      .from(example_categories)
      .where(
        and(
          cursor ? gt(example_categories.id, Number(cursor)) : undefined,
          search ? ilike(example_categories.name, `%${search}%`) : undefined,
        ),
      )
      .orderBy(asc(example_categories.id))
      .limit(limit + 1);
    const page = rows.slice(0, limit);

return {
      items: page.map(row => ({ id: String(row.id), label: row.name })),
      nextCursor: rows.length > limit ? String(page.at(-1)?.id) : null,
    };
  },
  find: async (c, ids) => {
    const numeric = ids.map(Number).filter(id => Number.isSafeInteger(id));
    if (numeric.length === 0) return [];

const rows = await c
      .get("db")
      .select({ id: example_categories.id, name: example_categories.name })
      .from(example_categories)
      .where(inArray(example_categories.id, numeric));

return rows.map(row => ({ id: String(row.id), label: row.name }));
  },
});
```

`list` feeds the picker one page at a time. `find` labels a saved selection and lets the API refuse an id that does not exist. Return `context`, such as `["Games"]`, on each resource to show where a nested resource sits. Both callbacks read the database, so the family never reaches the browser.

</Step>

<Step>

### Add it to the plugin [#add-it-to-the-plugin]

Pass the family to `buildApiPlugin`, and translate its label:

```ts title="plugins/example/src/config.api.ts"
buildApiPlugin({
  pluginId: CONFIG_PLUGIN.pluginId,
  moderation: { scopes: [exampleCategoryScope] }, // [!code ++]
  modules: [/* ... */],
});
```

```json title="plugins/example/src/locales/en.json"
{
  "@vitnode/example": {
    "moderation": {
      "category": {
        "label": "Categories",
        "desc": "Limit this permission to articles in some categories."
      }
    }
  }
}
```

Family ids are global. Two plugins registering the same id, or a permission naming a family nobody registers, stops the API at boot with a `ModerationRegistryError`.

</Step>

<Step>

### Tell the content model where a record sits [#tell-the-content-model-where-a-record-sits]

On the server-side model, name the base-table column that holds the resource id:

```ts title="plugins/example/src/database/articles.ts"
export const articleContent = createContentModel(articleContentType, {
  references: { category: () => example_categories.id },
  moderationScope: { column: "category", family: "example.category" }, // [!code ++]
});
```

The report permissions of `example.article` are now scoped by `example.category`. The server reads the column itself, so a client can never claim a record is in another category. The definition in `content/article.ts` stays browser-safe, without callbacks.

</Step>

</Steps>

## Check the result [#check-the-result]

Rebuild with `pnpm build:plugins` and restart `pnpm dev`. Open **AdminCP → Staff → Moderators**, edit a moderator and select the example plugin. **View reports** and **Claim, assign, annotate and resolve reports** now show a scope under the checkbox, and **Change** opens the category picker. See [Configure moderators](/docs/dev/moderation/configure-moderators).

## How grants combine [#how-grants-combine]

A user's effective moderator permissions come from their own staff entry and the entries of every role they hold:

- **Grants of one permission merge.** "View reports in A" from a role and "view reports in B" from the user give "view reports in A and B". "All resources" wins over a selection.
- **Permissions never combine across each other.** A role with "hide in A" and a user entry with "view in B" never allow hiding in B. Each permission keeps its own scope.
- **Dependencies are checked per resource.** Managing reports depends on viewing reports, so "manage in A" needs "view in A". Saving "manage in B" with only "view in A" is refused, and if broken data ever gets through, the effective scope of "manage" is cut down to where "view" is held.
- **Root roles and unrestricted entries** still allow everything, in every scope.

`isModerator` in the session means "has a moderator entry". It grants no permission by itself, and the ModCP shows only what the grants allow.

## Compatibility with unscoped grants [#compatibility-with-unscoped-grants]

Unscoped permissions work as before. A grant without a `scope` allows the permission everywhere.

When a plugin later makes an existing permission scoped, grants saved before that change have no scope. They keep meaning **all resources**, and the editor shows them as **All resources**. A new save always needs an explicit scope. The API answers `400` with `missing_scope` instead of guessing that a missing scope means "everything".

## Check a scope in your own code [#check-a-scope-in-your-own-code]

Pass the resource when you check a scoped permission:

```ts
const allowed = await checkStaffPermission(c, {
  type: "moderator",
  plugin: "@vitnode/example",
  module: "article",
  permission: "can_view_reports",
  resource: { family: "example.category", id: "2" },
});
```

A check without `resource` only passes for an unscoped or an **All resources** grant, so older code can never be widened by a selection. When a record moves to another resource, call `syncModerationReportScope(c, { pluginId, targetType, targetId })` from `@vitnode/core/api/moderation` after the move, so its reports follow it. The ModCP also re-reads the scope every time it opens a report.

# Limit who sees a notification (/docs/dev/notifications/access)

Add an `access` check to a notification type when the content behind it is private, such as a topic in a members-only forum. Core asks your check who may see the notification before delivering it, before emailing it and every time the inbox loads. A member who loses access stops seeing the item, even after it was delivered.

This guide continues the `forum.topic_reply` type from [Publish notifications](/docs/dev/notifications/publishing).

<Steps>

<Step>

### Add the access check [#add-the-access-check]

Add `access` to the type. It receives a batch of candidate user ids and returns the ones that may see the notification:

```ts title="plugins/forum/src/api/lib/notifications.ts"
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'
import { and, eq, inArray } from 'drizzle-orm'
import { z } from 'zod'

import { forum_topic_members } from '@/database/topic-members'

export const topicReplyNotification = buildNotificationType({
  id: 'forum.topic_reply',
  // other options unchanged
  // [!code ++:14]
  access: async ({ c, data, userIds }) => {
    const members = await c
      .get('db')
      .select({ userId: forum_topic_members.userId })
      .from(forum_topic_members)
      .where(
        and(
          eq(forum_topic_members.topicId, data.topicId),
          inArray(forum_topic_members.userId, userIds),
        ),
      )

return members.map((member) => member.userId)
  },
})
```

Answer the whole batch with one query. A batch holds up to 500 ids by default, so a query per user would run 500 times. When every candidate shares one answer, such as "is the topic still public?", check once and return `userIds` or `[]`.

</Step>

<Step>

### Remove notifications when content goes away [#remove-notifications-when-content-goes-away]

When a topic is deleted, take its notifications out of every inbox. Call `remove()` in the route that deletes the topic:

```ts title="plugins/forum/src/api/modules/topics/routes/delete.route.ts"
await c.get('notifications').remove({
  subject: { type: 'forum.topic', id: topic.id },
})
```

`remove()` matches the `subject` you passed to `publish()`, lowers the unread counts in the same transaction and returns how many items it deleted. To remove only some members, for example after kicking them from a private topic, add `type` and `userIds`:

```ts title="plugins/forum/src/api/modules/topics/routes/kick.route.ts"
await c.get('notifications').remove({
  subject: { type: 'forum.topic', id: topic.id },
  type: 'forum.topic_reply',
  userIds: removedMemberIds,
})
```

`remove()` keeps inboxes tidy, but it is not required for privacy. An item whose `access` check now says no already shows "This notification is no longer available." instead of its text.

</Step>

</Steps>

<Callout type="warn" title="A throwing access check delays delivery">
  If `access` throws while notifications are delivered, the whole batch fails
  and the queue retries it later. When the inbox loads, a throw turns that one
  item into the "no longer available" placeholder. Let real database errors
  throw, but do not throw for "no access": return fewer ids instead.
</Callout>

## Check the result [#check-the-result]

1. Publish a reply in a private topic with two members and one non-member listed in `recipients`. Only the two members get an inbox item.
2. Remove one member from the topic and reload their notifications. The item shows "This notification is no longer available." and no longer links to the topic.
3. Delete the topic. The item disappears from the remaining member's inbox, and their unread count drops at the same moment.

For the full `remove()` signature, see the [Notifications API reference](/docs/dev/notifications/reference#remove).

# Notifications in the AdminCP (/docs/dev/notifications/admincp)

Open **AdminCP → System → Notifications** (`/admin/core/system/notifications`) to see how notifications are doing, decide what members get by default and stop everything when you need to.

## Permissions [#permissions]

The screen uses the core `notifications` staff permission module. Grant it in **AdminCP → Staff → Administrators**, see [Staff permissions](/docs/dev/working-with-users/staff-permissions).

| Permission                 | Allows                                                       |
| -------------------------- | ------------------------------------------------------------ |
| `notifications.can_view`   | Open the screen and see activity and types                   |
| `notifications.can_edit`   | Change what each type does by default                        |
| `notifications.can_manage` | The **Settings** sheet and **Reset all members to defaults** |

## Check activity [#check-activity]

**Activity** shows four numbers for the last 24 hours, 7 days or 30 days, each compared with the period before:

- **Emails delivered**: notification emails that went out. Test emails do not count.
- **Failure rate**: failed emails out of every email attempted.
- **Events published**: notifications that plugins and core published.
- **Emails skipped**: emails that were due but not sent, for example because the member turned email off or already read the notification.

Hover or tap a trend line to see the count for one day, or one hour in the 24-hour view. Days follow the site's time zone, so "today" means the same to every administrator. When notifications are paused, a **Notifications are paused** banner shows above the numbers.

## Set what members get by default [#set-what-members-get-by-default]

**Notification types** lists every registered type, grouped by plugin. Each row shows what members get today, and opening it lets you change that. Changes save as you click.

| Choice                | Options                                                                       |
| --------------------- | ----------------------------------------------------------------------------- |
| **Member can edit**   | Off locks the type to the defaults. Members still get it but cannot change it |
| **Notification list** | Enabled by default, Not enabled by default, Disabled                          |
| **Push**              | Available, Disabled                                                           |
| **Email**             | Enabled by default, Not enabled by default, Disabled, plus the frequency      |

**Enabled by default** means members get it unless they turn it off. **Not enabled by default** means they get it only after turning it on. **Disabled** turns the channel off for everyone and hides it from members' settings. A type without an email version shows that it cannot be emailed.

Defaults apply to members who never chose for themselves. A member's own choice still wins unless **Member can edit** is off. Mandatory types always stay in the notification list and are always locked. See [How core decides what a member receives](/docs/dev/notifications/preferences#how-core-decides-what-a-member-receives).

**Reset all members to defaults** removes every member's own choices so everyone follows this screen again. The confirmation says how many members customized their settings. Members keep their time zone. The reset cannot be undone.

## Use the Settings sheet [#use-the-settings-sheet]

Select **Settings** in the top-right corner to open tools and the danger zone.

**Send a test email to me** queues a sample notification email to your own address. It only appears when an email adapter is configured, and it cannot send to anyone else.

Each danger zone action affects every member and asks for confirmation first:

| Action                                   | What happens                                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Pause all notifications**              | Nothing is delivered or emailed. New notifications are stored and wait. **Resume** sends everything that waited |
| **Cancel all queued emails**             | Emails that have not gone out, including the next digests, are skipped. Inbox items stay                        |
| **Mark everything as read for everyone** | Every unread notification becomes read and every badge drops to zero live                                       |
| **Delete all notifications**             | Empties every member's inbox. Type `delete all notifications` to confirm                                        |

Deleting keeps types, preferences, settings and email history, and cannot be undone.

The bottom of the sheet shows how long notifications are kept. Retention and worker batch sizes are set in your API config, see [Configure the workers](/docs/dev/notifications/queue-and-scale#configure-the-workers). Delivery lists, retries and unread count repair have no buttons on this screen. Use the [AdminCP endpoints](/docs/dev/notifications/reference#admincp-endpoints) for them.

# Email and digests (/docs/dev/notifications/email-and-digests)

A notification type can also reach members by email, either right away or bundled into a daily or weekly digest. You turn email on in the type, and each member picks one mode per type: `none`, `immediate`, `daily` or `weekly`. Core plans, sends, retries and records every email through your configured email adapter.

## Before you begin [#before-you-begin]

Configure an [email adapter](/docs/dev/email). Without one, no type offers email, and members see no email choice.

<Steps>

<Step>

### Turn on email for the type [#turn-on-email-for-the-type]

Add `email: true` and pick the default mode for members who never change it:

```ts title="plugins/forum/src/api/lib/notifications.ts"
export const topicReplyNotification = buildNotificationType({
  id: 'forum.topic_reply',
  // other options unchanged
  defaults: { inApp: true, email: 'daily' }, // [!code ++]
  email: true, // [!code ++]
})
```

`email: true` reuses the `title`, `body` and `target` from `present`. Each email links to the item and to **Manage notification preferences** on `/settings/notifications`. A default other than `'none'` without `email` throws when the module loads.

</Step>

<Step>

### Word the email separately (optional) [#word-the-email-separately-optional]

Pass a function instead of `true` when the email needs its own subject or button label:

```ts title="plugins/forum/src/api/lib/notifications.ts"
email: ({ data, t }) => ({
  subject: t('@acme/forum.notifications.topic_reply.email_subject', {
    title: data.topicTitle,
  }),
  title: t('@acme/forum.notifications.topic_reply.title', {
    title: data.topicTitle,
  }),
  actionLabel: t('@acme/forum.notifications.topic_reply.email_action'),
}),
```

It receives the same arguments as `present`, in the recipient's language. Add the new keys to `src/locales/api/en.json`.

</Step>

</Steps>

## How digests are scheduled [#how-digests-are-scheduled]

Daily digests go out at 08:00 and weekly digests on Monday at 08:00, in each member's time zone. The hour and day are the same for everyone, and members cannot change them.

- A daily digest covers the 24 hours before 08:00. A weekly one covers the seven days before Monday 08:00. A notification that arrives after 08:00 waits for the next digest.
- The time zone comes from the member's **Region** setting on `/settings`, then from their language, then UTC.
- Periods follow local time, so on the night clocks change a day lasts 23 or 25 hours. No day is skipped or sent twice.
- Each notification joins exactly one digest, and an empty digest is never sent.
- A digest lists up to 25 notifications, newest first, and says how many more are waiting.

The `notifications-schedule` cron plans digests every 5 minutes, so a digest can arrive up to 5 minutes after 08:00.

## What is checked at send time [#what-is-checked-at-send-time]

Right before an email or digest goes out, core checks each notification again: the member's current email mode, the type's policy in the AdminCP, the type's `access` check, and whether the member already read it.

Digests and delayed emails include only notifications that are still unread. A member who read or archived an item in the inbox does not get it by email too. A member who switched modes since the notification arrived gets it in the new mode, or not at all for `none`. A member who takes a type by email only has no inbox item to read, so their email always goes out.

## Delivery records and retries [#delivery-records-and-retries]

Every send, including test emails, is a row in `core_notification_deliveries`. List them with `GET /deliveries` in the [AdminCP API](/docs/dev/notifications/reference#admincp-endpoints).

| Status    | Meaning                                                                                     |
| --------- | ------------------------------------------------------------------------------------------- |
| `pending` | Waiting for its send time                                                                   |
| `sending` | Claimed by a worker                                                                         |
| `sent`    | The provider accepted it. `providerMessageId` holds the provider's id                       |
| `failed`  | All 5 attempts failed. `lastError` holds the error with addresses and tokens redacted       |
| `skipped` | Nothing to send. `skipReason` says why, such as `empty`, `email_disabled` or `user_missing` |

A failed attempt is retried after 10 seconds, then 20, 40 and 80. Every attempt passes the same `idempotencyKey` to your adapter, so a provider that deduplicates, such as Resend, never delivers a retry twice. SMTP through Nodemailer cannot deduplicate, so a crash between "accepted" and "recorded" can send one email twice. To forward the key from your own adapter, see [Custom email adapter](/docs/dev/email/custom-adapter#idempotency-and-the-return-value).

## Check the result [#check-the-result]

1. Open **AdminCP → System → Notifications**, select **Settings**, and run **Send a test email to me**. The email arrives at your own address.
2. Set **Replies to your topics** to **Right away** on `/settings/notifications`, then trigger a reply as another member. The email arrives within about a minute, as long as your [cron adapter](/docs/dev/cron) runs the queue worker.
3. If it does not, see [Emails are not sending](/docs/dev/notifications/troubleshooting#emails-are-not-sending).

# Inbox and realtime (/docs/dev/notifications/inbox-and-realtime)

Every recipient gets their own inbox items, and every member has one stored unread count. Each change to an inbox updates that count in the same database transaction and then pushes the new value to the member's open tabs. This page explains how read state, grouping and the live count behave, so you can predict what members see.

## Read and unread [#read-and-unread]

An inbox item is unread while it is not archived and the member has not read its latest activity. Each item has two counters:

- `activitySeq` starts at 1 and increases each time a grouped notification joins the item.
- `readSeq` records how far the member has read.

Opening `/notifications` or the bell never marks anything read. Opening an item, marking it read or **Mark all as read** does.

When the browser marks an item read, it sends the `activitySeq` it displayed as `throughSeq`. If a fourth reply joined the item after the bell rendered it, the item stays unread, because the member has not seen that reply yet.

**Mark all as read** marks everything that exists when the request takes the member's lock. A notification delivered a moment later stays unread, so nothing that arrives during the click is lost.

## Grouping [#grouping]

Types with [`grouping`](/docs/dev/notifications/notification-types#grouping) merge related notifications into one item per member, type, group key and time window:

- Windows are fixed UTC slots, not sliding ones. With a 60-minute window, 14:00 to 14:59 UTC share an item, and 15:00 starts a new one.
- A new notification in a read item makes it unread again, and one in an archived item brings it back to the inbox.
- Items sort by their latest activity, so a grouped item moves to the top when it grows.
- The unread count counts items, not notifications. Ten replies in one grouped item add 1.

## Items that are no longer available [#items-that-are-no-longer-available]

Before returning a page of the inbox, core checks every item again: the type is still registered, its stored data still parses, `access` still allows the member and `present` still renders. If any check fails, the item comes back as a placeholder with the title "This notification is no longer available." and no link.

The placeholder keeps its read state, so members can still read or archive it, and the unread count never includes an item they cannot clear. This covers deleted content, revoked access and uninstalled plugins.

## The live unread count [#the-live-unread-count]

The browser receives the same `{ unread, revision }` pair from three places:

1. The session payload, `user.notifications` in `GET /api/@vitnode/core/users/session`, read fresh on every request.
2. The WebSocket message `notificationsStateChannel`, sent after every committed inbox change.
3. `GET /api/@vitnode/core/notifications/state`.

`unread` is always the absolute count. `revision` increases with every change, and the browser keeps the state with the highest revision, so a slow response never undoes a newer realtime update. Messages are sent only after commit, so a rolled-back change never reaches the browser.

WebSocket messages missed while a tab was offline are not replayed. Instead, the browser reads `/state` again each time the socket connects, and when a tab returns after more than 30 seconds in the background. Without a socket, for example when the API runs inside the web app on the same origin, it reads `/state` every 60 seconds while the tab is visible.

When the count changes, open notification lists refresh once per burst: 1 second after the last change and at most 5 seconds after the first.

<Callout type="warn" title="Several API instances need Redis for realtime">
  With `REDIS_URL` set, realtime messages travel between API instances over
  Redis, so delivery on instance A reaches a tab connected to instance B.
  Without Redis, only tabs connected to the same instance update live. Others
  catch up on their next reconnect or page load. See
  [Redis](/docs/dev/advanced/redis).
</Callout>

## What core ships in the UI [#what-core-ships-in-the-ui]

| Piece                  | Where                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| Bell with unread badge | Site header on every screen size. Loads the recent list only when opened                  |
| Notifications page     | `/notifications`, with **All** and **Unread** tabs, a category filter and infinite scroll |
| Preferences            | `/settings/notifications`, see [Preferences](/docs/dev/notifications/preferences)         |

A default theme needs no wiring. To build your own bell, call the [member endpoints](/docs/dev/notifications/reference#member-endpoints) and listen to the [realtime channel](/docs/dev/notifications/reference#realtime-channel).

# Notifications (/docs/dev/notifications)

VitNode notifications give every member an inbox under the bell in the site header. A plugin calls `c.get("notifications").publish()` from an API route. Core then stores the notification, delivers it to each recipient, updates their unread count live and sends email to members who asked for it.

## What your plugin does and what core does [#what-your-plugin-does-and-what-core-does]

Your plugin decides who might care about something. Core decides who actually receives it, and how.

| Your plugin                                               | Core                                                                   |
| --------------------------------------------------------- | ---------------------------------------------------------------------- |
| Declares a notification type with `buildNotificationType` | Lists the type on every member's preferences page                      |
| Passes candidate user ids as `recipients`                 | Drops the actor, deleted users and members who turned the type off     |
| Answers "who may see this?" in `access`                   | Calls `access` in batches, again before email and when the inbox loads |
| Returns plain text from `present`                         | Strips markup, drops unsafe links and translates per recipient         |
| Sends one `idempotencyKey` per real-world event           | Ignores repeats, retries failed work and never delivers twice          |

## Notification or toast? [#notification-or-toast]

A notification is stored until the member reads or archives it. A toast is a short message sent over the WebSocket to open tabs, and it is gone after a reload.

| You want to                                                                     | Use                                                                                 |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Tell a member something they may look for later, such as a reply or an approval | `c.get("notifications").publish()`                                                  |
| Give feedback about something happening right now, such as "Import started"     | A toast with `c.get("realtime").sendToUser()`, see [WebSocket](/docs/dev/websocket) |

## Pick a guide [#pick-a-guide]

| You want to                                                  | Guide                                                                                      |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Send your first notification from a plugin                   | [Publish notifications](/docs/dev/notifications/publishing)                                |
| Hide notifications from members who cannot see the content   | [Limit who sees a notification](/docs/dev/notifications/access)                            |
| Send a notification by email or in a daily or weekly digest  | [Email and digests](/docs/dev/notifications/email-and-digests)                             |
| Replace a plugin's toasts with stored notifications          | [Move from toasts to notifications](/docs/dev/notifications/migration-and-troubleshooting) |
| Change what members get by default, or pause everything      | [Notifications in the AdminCP](/docs/dev/notifications/admincp)                            |
| Fix a bell that does not update, or email that never arrives | [Troubleshooting](/docs/dev/notifications/troubleshooting)                                 |
| Look up every option of `buildNotificationType`              | [Notification types](/docs/dev/notifications/notification-types)                           |
| Look up `publish()`, `remove()` and the REST endpoints       | [Notifications API reference](/docs/dev/notifications/reference)                           |

To understand what happens after `publish()`, read [Inbox and realtime](/docs/dev/notifications/inbox-and-realtime), [Preferences](/docs/dev/notifications/preferences) and [Queue and scale](/docs/dev/notifications/queue-and-scale).

# Move from toasts to notifications (/docs/dev/notifications/migration-and-troubleshooting)

Before stored notifications, a VitNode "notification" was a toast pushed over the WebSocket. It reached open tabs only and was gone after a reload. This guide upgrades your database and turns the toasts members would look for later into stored notifications. Looking for a fix instead? See [Troubleshooting](/docs/dev/notifications/troubleshooting).

<Steps>

<Step>

### Apply the database migration [#apply-the-database-migration]

Stored notifications add six `core_notification*` tables. Run the migrations once after upgrading `@vitnode/core`:

```bash tab="bun"
bun run db:migrate
```

```bash tab="pnpm"
pnpm db:migrate
```

```bash tab="npm"
npm run db:migrate
```

</Tabs>

In development, `pnpm dev` runs `vitnode db:prepare`, which applies them for you.

</Step>

<Step>

### Pick the toasts to keep [#pick-the-toasts-to-keep]

A reply, a mention, an approval or a finished export belongs in the inbox, because a member may look for it later. Feedback about something happening right now, such as "Import started", can stay a toast.

</Step>

<Step>

### Declare a type for each [#declare-a-type-for-each]

Declare and register one type per kept toast, as in [Publish notifications](/docs/dev/notifications/publishing):

```ts title="plugins/shop/src/api/lib/notifications.ts"
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'
import { z } from 'zod'

export const exportReadyNotification = buildNotificationType({
  id: 'shop.export_ready',
  version: 1,
  schema: z.object({ exportId: z.number() }),
  category: 'system',
  label: '@acme/shop.notifications.export_ready.label',
  defaults: { inApp: true, email: 'none' },
  present: ({ data, t }) => ({
    title: t('@acme/shop.notifications.export_ready.title'),
    target: `/shop/exports/${data.exportId}`,
  }),
})
```

</Step>

<Step>

### Replace the toast with `publish()` [#replace-the-toast-with-publish]

```ts title="plugins/shop/src/api/modules/exports/routes/finish.route.ts"
// [!code --:4]
c.get('realtime').sendToUser(user.id, notificationsChannel, {
  title: 'Your export is ready',
  type: 'success',
})
// [!code ++:7]
await c.get('notifications').publish({
  type: exportReadyNotification,
  recipients: [user.id],
  allowSelf: true,
  data: { exportId: job.id },
  idempotencyKey: `export:${job.id}`,
})
```

The bell updates over the same WebSocket, so members still see it right away. `allowSelf: true` matters here: the member who started the export is also the request's actor, and the actor is skipped by default.

</Step>

</Steps>

## Check the result [#check-the-result]

1. Run the export as a member, then reload the page. The notification is still under the bell, with an unread count.
2. Sign out and back in on another browser. The same notification is there.
3. On `/settings/notifications`, the new type is listed and can be turned off.

The AdminCP dashboard's **Send a notification** widget already works this way: it shows a toast and stores the message as a `core.admin_message` notification. Toasts sent with `sendToUser()` and `notificationsChannel` keep working unchanged, see [WebSocket](/docs/dev/websocket).

# Notification types (/docs/dev/notifications/notification-types)

A notification type describes one kind of notification: the data it stores, how it reads in the inbox, who may see it and what members get by default. You build it with `buildNotificationType()` and register it on your API plugin. For a guided first type, see [Publish notifications](/docs/dev/notifications/publishing).

## Signature [#signature]

```ts
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'

buildNotificationType<TData>(
  definition: NotificationTypeDefinition<TData>,
): NotificationTypeDefinition<TData>
```

It returns the definition unchanged after checking it. Pass that same object to `notificationTypes` and to `publish({ type })`, so TypeScript checks `data` against `schema` at every call site.

Register types on `buildApiPlugin({ notificationTypes })`, or on any module with `buildModule({ notificationTypes })`. Core collects them from every installed plugin when the API starts.

## Options [#options]

<TypeTable
  type={{
    id: {
      description:
        'Dot-separated id such as "forum.topic_reply": at least two segments of lowercase letters, digits, "_" or "-", at most 100 characters. Stored notifications refer to it, so never rename it.',
      type: 'string',
      required: true,
    },
    version: {
      description:
        'Integer, 1 or more. Increase it when schema changes shape, and add migrate.',
      type: 'number',
      required: true,
    },
    schema: {
      description:
        'Zod schema for data. Checked on publish and again whenever stored data is read.',
      type: 'z.ZodType<TData>',
      required: true,
    },
    category: {
      description:
        'Groups types on the preferences page and in inbox filters. 1 to 50 characters of a-z, 0-9, "_" or "-". Core translates account, content, social and system.',
      type: 'string',
      required: true,
    },
    label: {
      description: 'API message key for the type name on the preferences page.',
      type: 'string',
      required: true,
    },
    description: {
      description:
        'API message key for a one-line explanation under the label.',
      type: 'string',
    },
    defaults: {
      description:
        'What a member gets before changing anything. Administrators can override it in the AdminCP.',
      type: '{ inApp: boolean; email: "none" | "immediate" | "daily" | "weekly" }',
      required: true,
    },
    present: {
      description:
        "Renders one inbox item as plain text in the recipient's language.",
      type: '(args: NotificationPresentArgs<TData>) => { title: string; body?: string; target?: string | null }',
      required: true,
    },
    email: {
      description:
        'Turns on email for this type. true reuses present. A function writes the email separately. Required when defaults.email is not "none".',
      type: 'boolean | (args: NotificationPresentArgs<TData>) => { subject: string; title: string; body?: string; actionLabel?: string }',
    },
    access: {
      description:
        'Returns which of userIds may see the notification. Without it, every recipient may.',
      type: '(args: { c, data, subject, userIds }) => number[] | Promise<number[]>',
    },
    grouping: {
      description:
        'Merges related notifications that arrive in the same time window into one inbox item.',
      type: '{ windowMinutes: number; key?: (args: { data, subject }) => string | null }',
    },
    subjectType: {
      description:
        'The only subject type publish() accepts for this type, such as "forum.topic".',
      type: 'string',
    },
    mandatory: {
      description: 'Always delivered to the inbox. Members cannot change it.',
      type: 'boolean',
      default: 'false',
    },
    migrate: {
      description:
        'Upgrades data stored by an older version before it is parsed.',
      type: '(data: unknown, fromVersion: number) => unknown',
    },
  }}
/>

`buildNotificationType()` throws a `NotificationRegistryError` when the module loads if the id, category or subject type is invalid, `version` is below 1, `grouping.windowMinutes` is outside 1 to 10,080 (one week), or `defaults.email` is not `"none"` while `email` is missing. Two registered types with the same `id` stop the API from starting.

## `present` arguments [#present-arguments]

`present` runs on the API each time an item is listed or emailed. It receives:

A missing `label` translation shows the type id instead. Category names are looked up as `core.notifications.categories.<category>`, then `<pluginId>.notifications.categories.<category>`.

## How core cleans `present` output [#how-core-cleans-present-output]

Core cleans what `present` returns before anyone sees it:

- `title` and `body` are plain text. Markup is never rendered, whitespace is collapsed and each string is cut at 500 characters.
- `target` must be a path on the same site, such as `/forum/topics/42`. Absolute URLs, `//host`, `javascript:` and backslashes are dropped, and the item renders without a link.
- If `present` throws or returns an empty title, the item shows "This notification is no longer available." and the error is logged.

## `access` [#access]

Core calls `access` once per delivery batch, again before each email or digest, and each time a member's inbox loads. It receives a bounded batch of user ids, never the whole audience. A worked example is in [Limit who sees a notification](/docs/dev/notifications/access).

## `grouping` [#grouping]

```ts title="plugins/forum/src/api/lib/notifications.ts"
grouping: {
  windowMinutes: 60,
  key: ({ data }) => `topic:${data.topicId}`,
},
```

Notifications with the same type and key, for the same member, in the same window join one inbox item, such as "Alex and 4 others replied to Shipping day". Windows are fixed UTC slots: with 60 minutes, 14:00 to 14:59 is one window. The key defaults to the subject. A notification without a subject, or a `key` that returns `null`, is never grouped. Use `actors`, `actorCount` and `eventCount` in `present` to word a grouped item:

```json title="plugins/forum/src/locales/api/en.json"
"title": "{others, plural, =0 {{name} replied} one {{name} and # other replied} other {{name} and # others replied}} to {title}"
```

## `version` and `migrate` [#version-and-migrate]

Stored notifications outlive your code. When `schema` changes shape, increase `version` and make `migrate` upgrade the old data. Here version 1 stored `title`, and version 2 renames it to `topicTitle`:

```ts title="plugins/forum/src/api/lib/notifications.ts"
export const topicReplyNotification = buildNotificationType({
  id: 'forum.topic_reply',
  version: 2,
  schema: z.object({ topicId: z.number(), topicTitle: z.string() }),
  migrate: (data, fromVersion) => {
    if (fromVersion !== 1) return data
    const old = data as { title: string; topicId: number }

return { topicId: old.topicId, topicTitle: old.title }
  },
  // other options unchanged
})
```

Data that cannot be upgraded is never shown. That covers a missing `migrate`, a stored version newer than the code, a thrown error or a failed parse. A notification not yet delivered is marked failed, and inbox items show the "no longer available" placeholder.

## `mandatory` [#mandatory]

Set `mandatory: true` for account notices members must not miss, such as "Your role changed". The type always reaches the inbox, ignores AdminCP policies that would disable it, and shows as locked on the preferences page. Its email follows the installation default.

Password resets, email verification and sign-in codes are not notifications. Keep sending them with `c.get("email").send()`, so they arrive even for members who turned every notification off.

# Preferences (/docs/dev/notifications/preferences)

Members choose, per notification type, whether it shows in their notification list, whether it comes as push and how it reaches them by email. Core builds the page at `/settings/notifications` from the registered types, so a new plugin's types appear there with no UI code.

## The settings page [#the-settings-page]

`/settings/notifications` has two parts:

- **Where notifications reach you** turns push and email on or off for the whole account. The **Email** switch turns notification email off for every type the member can change, after a confirmation.
- **What you get notified about** lists one row per type. The bell, phone and mail icons show what is on. Opening a row shows a switch per channel and, when email is on, a choice between **Right away**, **Daily digest** and **Weekly digest**.

Every change saves at once and confirms with a toast.

<Callout title="Push is not delivered yet">
  Members can turn push on, and core stores and respects those choices, but
  VitNode does not send push notifications yet. Nothing changes for members when
  delivery arrives.
</Callout>

## How core decides what a member receives [#how-core-decides-what-a-member-receives]

Core resolves the notification list, push and email separately, so a member can take a type by email only, in the list only, both or neither. For each type it checks, in this order:

1. **Disabled by the installation.** The member gets nothing. Mandatory types skip this check.
2. **Mandatory type.** Always in the notification list. Email follows the installation default.
3. **The member's own choice**, unless an administrator turned off **Member can edit** for the type in the [AdminCP](/docs/dev/notifications/admincp#set-what-members-get-by-default).
4. **The installation default** set in the AdminCP.
5. **The type's own `defaults`.**

A channel the AdminCP set to **Disabled** is off for everyone and disappears from members' settings. Locked types show "Set by the admin", and the API refuses changes to them with `400`. Push is on by default wherever the installation allows it.

A type offers email only when it declares `email`, an [email adapter](/docs/dev/email) is configured, and the AdminCP has not set its email to **Disabled**. There is no installation-wide email switch: to stop one kind of email, disable email on that type.

### Example [#example]

`forum.topic_reply` defaults to `{ inApp: true, email: 'daily' }`. An administrator changed its email default to weekly.

| Member                                 | Notification list | Email                            |
| -------------------------------------- | ----------------- | -------------------------------- |
| Never opened preferences               | yes               | weekly, the installation default |
| Chose **Right away**                   | yes               | immediate, their choice          |
| Turned the notification list off       | no                | weekly, email is independent     |
| Anyone, after email is set to Disabled | yes               | none                             |

## Time zone [#time-zone]

Digests go out at 08:00 in the member's time zone. The time zone belongs to the account, not to notifications: members set it under **Region** on `/settings`, and **Use this device's time zone** fills it in from the browser. Without one, core uses the time zone of the member's language, then UTC. See [How digests are scheduled](/docs/dev/notifications/email-and-digests#how-digests-are-scheduled).

## Account email is not a notification [#account-email-is-not-a-notification]

Password resets, email verification and sign-in codes are sent with `c.get("email").send()`. They never pass through notification preferences, AdminCP policies or digests, so a member who turned every notification off still receives them. Use a [mandatory type](/docs/dev/notifications/notification-types#mandatory) for account notices that also belong in the inbox.

# Publish notifications (/docs/dev/notifications/publishing)

This guide notifies a topic's author when someone replies to their topic. You declare a notification type once, register it on your API plugin, and publish it from the route that saves the reply. The examples use a forum plugin with the id `@acme/forum`.

## Before you begin [#before-you-begin]

You need a plugin with an API part (`src/config.api.ts`) and a route that writes to the database. See [Create a plugin](/docs/dev/plugins/create) if you do not have one yet.

<Steps>

<Step>

### Declare the notification type [#declare-the-notification-type]

Create a file for your plugin's notification types:

```ts title="plugins/forum/src/api/lib/notifications.ts"
import { buildNotificationType } from '@vitnode/core/api/lib/notifications/registry'
import { z } from 'zod'

export const topicReplyNotification = buildNotificationType({
  id: 'forum.topic_reply',
  version: 1,
  schema: z.object({ topicId: z.number(), topicTitle: z.string() }),
  category: 'social',
  label: '@acme/forum.notifications.topic_reply.label',
  defaults: { inApp: true, email: 'none' },
  present: ({ data, t }) => ({
    title: t('@acme/forum.notifications.topic_reply.title', {
      title: data.topicTitle,
    }),
    target: `/forum/topics/${data.topicId}`,
  }),
})
```

`id` is permanent, because stored notifications refer to it. `schema` checks the `data` you publish. `present` turns that data into the inbox text, in the recipient's language, every time the inbox loads. Every option is listed in [Notification types](/docs/dev/notifications/notification-types).

</Step>

<Step>

### Add the messages [#add-the-messages]

The API renders notification text, so the strings belong in your plugin's API messages:

```json title="plugins/forum/src/locales/api/en.json"
{
  "@acme/forum": {
    "notifications": {
      "topic_reply": {
        "label": "Replies to your topics",
        "title": "New reply in {title}"
      }
    }
  }
}
```

`label` names the type on the member's preferences page. If your plugin has no `src/locales/api/` folder yet, create it as shown in [Shipping translations with a plugin](/docs/dev/i18n/server#shipping-translations-with-a-plugin).

</Step>

<Step>

### Register the type [#register-the-type]

Pass the type and the API messages to `buildApiPlugin()`:

```ts title="plugins/forum/src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { topicReplyNotification } from '@/api/lib/notifications' // [!code ++]
import { topicsModule } from '@/api/modules/topics/topics.module'
import { CONFIG_PLUGIN } from '@/const'
import messages from '@/locales/api'

export const forumApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    messages,
    notificationTypes: [topicReplyNotification], // [!code ++]
    modules: [topicsModule],
  })
```

Core collects the types of every installed plugin when the API starts, so restart the API after adding one. Two types with the same `id` stop the API from starting, with an error that names both plugins.

</Step>

<Step>

### Publish in the reply route [#publish-in-the-reply-route]

In the handler that saves the reply, publish inside the same transaction:

```ts title="plugins/forum/src/api/modules/topics/routes/reply.route.ts"
await c.get('db').transaction(async (tx) => {
  const [reply] = await tx
    .insert(forum_replies)
    .values({ topicId: topic.id, authorId: user.id, content })
    .returning()

// [!code ++:8]
  await c.get('notifications').publish({
    type: topicReplyNotification,
    tx,
    recipients: [topic.authorId],
    subject: { type: 'forum.topic', id: topic.id },
    data: { topicId: topic.id, topicTitle: topic.title },
    idempotencyKey: `reply:${reply.id}`,
  })
})
```

`topic`, `user` and `content` come from your existing route. Because of `tx`, the notification is saved together with the reply: a rolled-back reply notifies nobody, and a saved reply always notifies, even if the server stops right after the commit. `subject` names what the notification is about. Core uses it to group notifications and to [remove them later](/docs/dev/notifications/access#remove-notifications-when-content-goes-away).

</Step>

</Steps>

`publish()` returns `{ eventId, duplicate }` and does not wait for delivery. Delivery starts after your route sends its response, so a large audience never slows the request down.

<Callout type="warn" title="A rejected publish rolls back your write">
  `publish()` throws a `NotificationPublishError` when `data` does not match the
  schema or the type is not registered. Inside a transaction, that error rolls
  back the reply too. Catch it if the notification is optional for the write.
  See [Errors](/docs/dev/notifications/reference#errors).
</Callout>

## Choose an idempotency key [#choose-an-idempotency-key]

The `idempotencyKey` names the real-world event, not the attempt to publish it. Publishing the same type with the same key again does nothing and returns the first event with `duplicate: true`. Retries, double clicks and replayed event listeners never notify twice.

| Event                          | Good key                    | Bad key                  |
| ------------------------------ | --------------------------- | ------------------------ |
| A reply was posted             | `reply:${reply.id}`         | `reply:${Date.now()}`    |
| An article was first published | `post-published:${post.id}` | `post-${post.updatedAt}` |
| An export finished             | `export:${job.id}`          | `crypto.randomUUID()`    |

Use a random key only when every call really is a new message, such as an administrator sending the same announcement twice on purpose.

## Choose the recipients [#choose-the-recipients]

`recipients` holds the user ids your plugin picked, up to 100,000 per publish. Core removes duplicates and the actor, which is the signed-in admin or user of the request. When the notification is delivered, core also skips deleted users, members who turned the type off and anyone your type's [`access` check](/docs/dev/notifications/access) rejects.

To notify the actor about their own work, set `allowSelf: true`:

```ts title="plugins/forum/src/api/modules/exports/routes/finish.route.ts"
await c.get('notifications').publish({
  type: exportReadyNotification,
  recipients: [user.id],
  allowSelf: true,
  data: { exportId: job.id },
  idempotencyKey: `export:${job.id}`,
})
```

A queue task or cron job has no signed-in user. Pass the real actor as `actorId`, or `actorId: null` for a system notification.

## Check the result [#check-the-result]

1. Sign in as a second user and reply to a topic started by someone else. Replying to your own topic notifies nobody, because the actor is skipped.
2. Sign in as the topic author. Within a few seconds the bell shows an unread count, and the new item links to `/forum/topics/{id}`.
3. Open `/settings/notifications`. **Replies to your topics** is listed under **What you get notified about**, in the **Social** group once more than one category exists.

If nothing arrives, see [Troubleshooting](/docs/dev/notifications/troubleshooting#notifications-arrive-late-or-never).

# Queue and scale (/docs/dev/notifications/queue-and-scale)

Notifications run on VitNode's database-backed [queue](/docs/dev/advanced/queue) and [cron](/docs/dev/cron). No extra service is needed, but the queue worker must run: without a working cron adapter, nothing is delivered in the background.

## Queue tasks and cron jobs [#queue-tasks-and-cron-jobs]

All of these belong to `@vitnode/core` and appear in **AdminCP → Advanced → Queue**.

| Name                     | Kind                  | Does                                                                    |
| ------------------------ | --------------------- | ----------------------------------------------------------------------- |
| `notifications-fanout`   | Task, 10 attempts     | Delivers one notification to its recipients, batch by batch             |
| `notifications-email`    | Task, 5 attempts      | Sends due emails and digests                                            |
| `notifications-cleanup`  | Task, 3 attempts      | Removes notifications older than the retention period                   |
| `notifications-schedule` | Cron, every 5 minutes | Plans digests, recovers stalled work and queues the email task when due |
| `notifications-cleanup`  | Cron, daily at 02:00  | Queues the cleanup task                                                 |

A request that publishes starts delivery right after its response is sent. Anything that misses that, such as a publish from a queue task, waits for the queue worker, which runs every minute.

## Batched delivery [#batched-delivery]

The fan-out task walks the recipients in batches of `fanoutBatchSize`, 500 by default. Each batch is one short transaction that filters out deleted users, opted-out members and anyone `access` rejects, then writes inbox items, unread counts and immediate email deliveries, and saves its progress on the event. Realtime updates go out after the batch commits.

- **A crash loses at most one batch.** The retry continues after the last saved batch.
- **A batch that runs twice changes nothing.** Core keeps one receipt per notification and member, and only members without a receipt get an item.
- **Large audiences do not block the queue.** One task stops after 20 seconds and queues a new task for the rest.
- **No deadlocks between writers.** Every inbox write locks the affected members in user id order, so concurrent writers wait for each other instead.

The integration test `fanout.load.integration.test.ts` delivers one notification to 1,000 members with batches of 200, with two workers racing on the same event. It checks that every member gets exactly one item, that `access` runs about once per batch and that the number of queries stays below the number of recipients.

## Recovery [#recovery]

| Stuck work                                     | Recovered by                                                                |
| ---------------------------------------------- | --------------------------------------------------------------------------- |
| Queue task left processing by a stopped worker | The queue worker, after 15 minutes                                          |
| Notification unfinished with no task left      | `notifications-schedule`, after 10 minutes, by queuing a new task           |
| Email left in `sending`                        | `notifications-schedule`, after 15 minutes, by setting it back to `pending` |
| Two workers on one notification                | A row lock. The second waits, then continues from the saved progress        |

## Retention [#retention]

The nightly cleanup removes, in batches:

- inbox items with no activity for `retentionDays`, lowering unread counts for unread ones;
- older notifications that no inbox item points to;
- finished email delivery records older than `retentionDays`;
- pending digest email for notifications no digest picked up within 14 days. The inbox items stay.

## Configure the workers [#configure-the-workers]

How much work each run does and how long notifications are kept are deployment settings, so they live in your API config, not in the AdminCP. Add a `notifications` block to `buildApiConfig`:

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  // other options unchanged
  // [!code ++:6]
  notifications: {
    retentionDays: 30,
    fanoutBatchSize: 1000,
    emailBatchSize: 100,
    emailConcurrency: 8,
  },
})
```

| Name               | Type     | Required | Default | Description                                             |
| ------------------ | -------- | -------- | ------- | ------------------------------------------------------- |
| `retentionDays`    | `number` | No       | `90`    | Days to keep notifications, from 1 to 3,650             |
| `fanoutBatchSize`  | `number` | No       | `500`   | Recipients per delivery transaction, from 10 to 5,000   |
| `emailBatchSize`   | `number` | No       | `50`    | Emails one worker run picks up, from 1 to 500           |
| `emailConcurrency` | `number` | No       | `4`     | Emails sent at the same time during a run, from 1 to 20 |

A value outside its range is clamped to the nearest limit, and a value that is not a whole number falls back to the default. Restart the API to apply a change.

The defaults suit most sites. Raise `fanoutBatchSize` when one announcement to a huge audience needs too many runs, and `emailConcurrency` when your email provider allows more parallel sends. Lower `emailBatchSize` when a slow provider makes runs time out.

# Notifications API reference (/docs/dev/notifications/reference)

`c.get("notifications")` is available in every Hono route, event listener and queue task. This page lists its methods, the REST endpoints behind the bell and the AdminCP screen, and the WebSocket channel that carries the unread count. For the type definition, see [Notification types](/docs/dev/notifications/notification-types).

## Methods [#methods]

| Method          | Returns                                            | Behavior                                                                 |
| --------------- | -------------------------------------------------- | ------------------------------------------------------------------------ |
| `publish(args)` | `Promise<{ eventId: number; duplicate: boolean }>` | Stores one event and queues its delivery. Does not wait for delivery     |
| `remove(args)`  | `Promise<number>`                                  | Deletes matching inbox items and lowers unread counts. Returns the count |
| `state(userId)` | `Promise<{ unread: number; revision: number }>`    | Reads one member's stored unread count                                   |

### `publish` [#publish]

<TypeTable
  type={{
    type: {
      description:
        'The registered definition, or its id. A different object with the same id is rejected.',
      type: 'NotificationTypeDefinition<TData> | string',
      required: true,
    },
    data: {
      description: "Checked against the type's schema.",
      type: 'TData',
      required: true,
    },
    idempotencyKey: {
      description:
        'Names the real-world event, 1 to 255 characters. Unique per plugin and type.',
      type: 'string',
      required: true,
    },
    recipients: {
      description:
        'Candidate user ids, at most 100,000 after duplicates are removed. Without it, the event is stored and delivers nothing.',
      type: 'readonly number[]',
    },
    subject: {
      description:
        "What the notification is about. Used by grouping and remove(). Must match the type's subjectType.",
      type: '{ type: string; id: number | string }',
    },
    tx: {
      description:
        'Your transaction. The event and its delivery task commit or roll back with your write.',
      type: 'Transaction',
    },
    actorId: {
      description:
        'Who caused it. Defaults to the signed-in admin, then the signed-in user. Pass null for a system notification.',
      type: 'number | null',
    },
    allowSelf: {
      description: 'Deliver to the actor too.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

Publishing the same type and `idempotencyKey` again returns the first event with `duplicate: true`.

### `remove` [#remove]

Without `type` and `userIds`, `remove()` deletes every item about the subject for everyone.

### `state` [#state]

```ts title="plugins/forum/src/api/modules/topics/routes/summary.route.ts"
const { unread, revision } = await c.get('notifications').state(user.id)
```

`revision` increases with every change to the member's inbox, so a client can tell a newer count from an older one.

## Errors [#errors]

`publish()` throws a `NotificationPublishError` before writing anything when:

- the type is not registered, or `type` is a different object than the registered one;
- `data` fails the schema. The message lists each failing path;
- `idempotencyKey` is empty or longer than 255 characters after trimming;
- `subject` has an invalid type or id, or a type other than the type's `subjectType`;
- there are more than 100,000 recipients.

It also throws when two transactions publish the same key at the same moment and the first has not committed. Retry after the first commits, and the call returns `duplicate: true`.

## Member endpoints [#member-endpoints]

Every route acts on the signed-in member and answers `401` to guests. Paths are relative to `/api/@vitnode/core/notifications`.

| Method | Path            | Behavior                                                                                                               |
| ------ | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `GET`  | `/`             | One page of items, newest activity first. Query: `limit` (1 to 50, default 20), `cursor`, `unread`, `category`, `type` |
| `GET`  | `/state`        | `{ unread, revision }`                                                                                                 |
| `POST` | `/{id}/read`    | Marks one item read. Optional body `{ throughSeq }`                                                                    |
| `POST` | `/{id}/unread`  | Marks one item unread again                                                                                            |
| `POST` | `/{id}/archive` | Hides one item from the inbox. New activity brings it back                                                             |
| `POST` | `/read-all`     | Marks everything read. Optional body `{ category }`                                                                    |
| `GET`  | `/preferences`  | Every type the member can see, with their channels                                                                     |
| `PUT`  | `/preferences`  | Saves `{ types: { [typeId]: { inApp?, push?, email? } } }`. Other types keep their choices                             |

The mark routes return the new `{ unread, revision }`. Another member's item id answers `404`, like a missing one. Call these routes with the [fetcher](/docs/dev/fetcher):

```ts
const state = await fetcher({
  plugin: '@vitnode/core',
  method: 'get',
  module: 'notifications',
  path: '/state',
})
```

A member's time zone, used for digests, is saved with `PUT /api/@vitnode/core/users/me/time-zone` and the body `{ "timeZone": "Europe/Warsaw" }`, or `null` to follow their language.

## AdminCP endpoints [#admincp-endpoints]

Paths are relative to `/api/@vitnode/core/admin/notifications` and need an AdminCP session with the listed [staff permission](/docs/dev/working-with-users/staff-permissions) in the `notifications` module.

| Method | Path                         | Permission   | Behavior                                                           |
| ------ | ---------------------------- | ------------ | ------------------------------------------------------------------ |
| `GET`  | `/overview`                  | `can_view`   | Registered types, installation settings and delivery health        |
| `GET`  | `/stats`                     | `can_view`   | Activity numbers. Query: `range` (`24h`, `7d`, `30d`), `timeZone`  |
| `GET`  | `/deliveries`                | `can_view`   | Email deliveries, newest first. Query: `status`, `limit`, `cursor` |
| `PUT`  | `/types/{type}`              | `can_edit`   | Merges the body into the type's policy                             |
| `POST` | `/test-email`                | `can_manage` | Queues a test email to the signed-in administrator only            |
| `POST` | `/reconcile`                 | `can_manage` | Compares unread counts with the inbox. Body `{ dryRun, userId? }`  |
| `POST` | `/deliveries/{id}/retry`     | `can_manage` | Retries one failed delivery with the same idempotency key          |
| `POST` | `/pause`                     | `can_manage` | Pauses delivery and email                                          |
| `POST` | `/resume`                    | `can_manage` | Resumes and re-queues events that waited                           |
| `POST` | `/emails/cancel`             | `can_manage` | Skips every email that has not gone out                            |
| `POST` | `/read-all`                  | `can_manage` | Marks every member's notifications read                            |
| `POST` | `/delete-all`                | `can_manage` | Deletes every member's notifications                               |
| `POST` | `/members/reset-preferences` | `can_manage` | Clears every member's own choices                                  |

The body of `PUT /types/{type}` accepts any of these keys:

```json
{
  "allowInApp": true,
  "inApp": false,
  "allowPush": true,
  "allowEmail": true,
  "email": "daily",
  "memberCanEdit": false
}
```

`POST /reconcile` only reports by default: `dryRun` is `true` unless you send `false`. It returns `{ mismatched, corrected }`.

## Realtime channel [#realtime-channel]

Every committed change to a member's inbox sends `notificationsStateChannel` from `@vitnode/core/ws/notifications` to that member's open tabs:

```ts
interface NotificationStateMessage {
  unread: number
  revision: number
  reason:
    | 'created'
    | 'read'
    | 'unread'
    | 'read_all'
    | 'archived'
    | 'removed'
    | 'reconciled'
  notificationId?: number
}
```

`unread` is always the absolute count, never a change of one. The toast channel, `notificationsChannel`, lives in the same module. See [WebSocket](/docs/dev/websocket).

AdminCP actions also emit events such as `notifications.paused` and `notifications.type.updated`. See [Built-in events](/docs/dev/events/built-in-events).

# Troubleshooting notifications (/docs/dev/notifications/troubleshooting)

Each section below starts from a symptom and lists the checks in the order that finds the cause fastest.

## The bell does not update live [#the-bell-does-not-update-live]

- **Check the WebSocket.** The browser needs a working `/api/ws` connection. See [WebSocket](/docs/dev/websocket). Without one, the bell still catches up every 60 seconds while the tab is visible.
- **Running several API instances?** Set `REDIS_URL`. Without Redis, live updates reach only tabs connected to the instance that delivered the notification. Other tabs catch up on reconnect or page load.

## Notifications arrive late or never [#notifications-arrive-late-or-never]

A publishing request starts delivery right after its response. Everything else is delivered by the queue worker, which your cron adapter runs every minute.

1. **The cron adapter is not calling the queue worker.** In development there is no `CRON_SECRET`, so queued tasks wait until you run them. See [Cron](/docs/dev/cron).
2. **Notifications are paused.** The AdminCP notifications screen shows a **Notifications are paused** banner. See [Use the Settings sheet](/docs/dev/notifications/admincp#use-the-settings-sheet).
3. **The delivery task failed.** **AdminCP → Advanced → Queue** lists failed `notifications-fanout` tasks with the error.
4. **The member never gets it.** The actor is skipped unless you pass `allowSelf: true`, and members who turned the type off or fail your `access` check get nothing. See [Choose the recipients](/docs/dev/notifications/publishing#choose-the-recipients).

## Emails are not sending [#emails-are-not-sending]

1. **No email adapter.** Run **Send a test email to me** from the AdminCP [Settings sheet](/docs/dev/notifications/admincp#use-the-settings-sheet). If the tool is missing, no [email adapter](/docs/dev/email) is configured.
2. **Email is disabled for the type.** Check the type's **Email** column in [the AdminCP](/docs/dev/notifications/admincp#set-what-members-get-by-default).
3. **The member gets no email for the type.** The default may be **Not enabled by default**, or the member chose otherwise.
4. **The delivery was skipped or failed.** List deliveries with `GET /deliveries` from the [AdminCP endpoints](/docs/dev/notifications/reference#admincp-endpoints). `failed` shows a redacted error. `skipped` shows a reason, such as `empty` when everything was already read.

Digests go out only after their period ends, at 08:00 in the member's time zone, and include only notifications that are still unread.

## The digest came at the wrong time [#the-digest-came-at-the-wrong-time]

Digests follow the time zone the member set under **Region** on `/settings`, then the time zone of their language, then UTC. The scheduler runs every 5 minutes, so a digest can arrive up to 5 minutes after 08:00.

## The unread count looks wrong [#the-unread-count-looks-wrong]

Every inbox change updates the count in the same transaction, so a wrong count is a bug worth reporting. To check and repair counts, call `POST /reconcile` from the [AdminCP endpoints](/docs/dev/notifications/reference#admincp-endpoints). It only reports mismatches unless you send `{ "dryRun": false }`, which also pushes the corrected badge to open tabs.

## Items say "This notification is no longer available" [#items-say-this-notification-is-no-longer-available]

The item is a placeholder. The content was deleted, the member lost access, the plugin was uninstalled, or the stored data no longer matches the type's schema and `migrate` could not upgrade it. Members can still read or archive the item. Plugins can tidy these up with [`remove()`](/docs/dev/notifications/access#remove-notifications-when-content-goes-away).

# AdminCP passkey sign-in (/docs/dev/passkeys/admincp)

Staff can sign in to the AdminCP at `/admin` with the same passkey they use on the community site - fingerprint, face, PIN or security key, no password to type. It uses the passkeys you already [configured](/docs/dev/passkeys), so there is nothing extra to switch on. If passkeys are enabled, the **Sign in with a passkey** button shows up on the AdminCP login screen.

The AdminCP is still the high-security zone, so this flow is stricter than the public one:

- a **fresh AdminCP-only challenge** that lives for **two minutes** and works exactly once
- **user verification is required** - just tapping a key doesn't count
- **staff access is checked live** on the server at sign-in
- it creates an **AdminCP session only**, and never upgrades a public one

## For staff: the short version [#for-staff-the-short-version]

### Add a passkey (once) [#add-a-passkey-once]

1. Sign in to the AdminCP at `/admin` with your **email and password**.
2. In the **same browser**, go to the community site, sign in, and open **Settings → Security**.
3. Select **Add a passkey** and confirm with your fingerprint, face or PIN.

</Step>
<Step>

### Sign in with it [#sign-in-with-it]

1. Go to `/admin`.
2. Select **Sign in with a passkey**.
3. Pick your passkey and confirm with your fingerprint, face or PIN.

You'll land wherever you were heading in the AdminCP.

</Step>
</Steps>

<Callout type="info">
  Why the password first? Your account has AdminCP access, so VitNode only lets
  it add a passkey while an AdminCP session for **you** is open in that browser.
  That way a hijacked social login can't quietly add a passkey and walk into the
  AdminCP.
</Callout>

## Enrollment [#enrollment]

Passkeys are enrolled in one place - **Settings → Security** - and one passkey works for both the site and the AdminCP. Nothing is stored per area, so there's no second passkey to manage.

For accounts that **currently have AdminCP access**, both enrollment steps (`/register/options` and `/register`) also require the browser to hold a valid AdminCP session for the same user. Without one, the API answers `403 admin_session_required` and the settings page explains what to do. Members without staff access enroll exactly as before.

The check runs at both steps, so an AdminCP session that expires or is signed out mid-ceremony stops the passkey from being saved.

## Sign-in [#sign-in]

1. `POST /api/@vitnode/core/users/passkeys/admin-sign-in/options` issues request options with `userVerification: "required"` and no `allowCredentials`, so the browser offers any passkey saved for your RP ID. It stores a new challenge with the ceremony `admin_sign_in` and sets it in the HttpOnly cookie `<cookieName>_passkey_admin_sign_in`.
2. The browser asks the authenticator for an assertion.
3. `POST /api/@vitnode/core/users/passkeys/admin-sign-in` then:
   - **consumes** the challenge atomically, scoped to the cookie's token hash, the `admin_sign_in` ceremony and "not expired". A public sign-in or registration challenge never matches, and a replay always fails.
   - **verifies** the assertion with SimpleWebAuthn against your configured `origins` and `rpId`, with `requireUserVerification: true`, the same user-handle and signature-counter checks as public sign-in.
   - **resolves the user from the stored credential** - never from anything else the browser sends, and never from the public session cookie.
   - **checks staff access right now**, skipping the cache, and counting the user's primary role, every secondary role and any root role. Someone whose access was removed gets `403 not_staff`, even though their passkey is still valid.
   - only then calls `SessionAdminModel.createSessionByUserId()` - the same call the password form makes - which sets the `vitnode_auth_admin` cookie.

The routes live under `users/passkeys` rather than `admin/` on purpose: every `/admin/*` API path demands an AdminCP session, which nobody has yet while signing in.

## Sessions stay separate [#sessions-stay-separate]

|                                | Public passkey sign-in (`/login`) | AdminCP passkey sign-in (`/admin`)     |
| ------------------------------ | --------------------------------- | -------------------------------------- |
| Challenge ceremony             | `authentication`                  | `admin_sign_in`                        |
| Challenge lifetime             | 5 minutes                         | 2 minutes                              |
| User verification              | Required                          | Required                               |
| Staff access checked           | No                                | Yes, at sign-in time                   |
| Creates                        | Public session (`vitnode_auth`)   | AdminCP session (`vitnode_auth_admin`) |
| Reads the other area's session | No                                | No                                     |

A public session never turns into an AdminCP session - not after a passkey sign-in, not after SSO, not after a password sign-in. Signing out of one area leaves the other alone, exactly as described in [Authentication](/docs/dev/advanced/auth).

Social SSO never issues an AdminCP session either. SSO providers only sign people in to the public site, and the staff enrollment rule above means an SSO-only session can't be turned into an AdminCP passkey.

Once signed in, an AdminCP session behaves like one started with a password: staff access is re-checked on every request, so revoking it ends the session on the next request.

## Recovery [#recovery]

- **Password stays.** The AdminCP password form is untouched. It's the way in for staff who haven't added a passkey yet, and the fallback when a passkey is lost.
- **Lost the passkey?** Sign in to the AdminCP with your password, then add a new passkey in **Settings → Security** and remove the old one there.
- **Forgot the password too?** Use **Forgot password?** on the public `/login` page, then sign in to the AdminCP with the new password.
- The [last-recovery-method rule](/docs/dev/passkeys#keeping-members-locked-in-the-good-way) still applies, so you can't remove the last way into your account.

## What people see [#what-people-see]

| Message                        | Why                                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Passkey sign-in cancelled      | The browser prompt was closed or timed out. Try again.                                                      |
| That took a little too long    | The two-minute challenge expired, was already used, or the cookie was blocked. Start again.                 |
| Passkey not recognized         | The passkey was removed, belongs to another RP ID, or failed verification (including no user verification). |
| No AdminCP access              | The passkey is valid, but the account doesn't have AdminCP access right now.                                |
| Passkeys aren't supported here | The browser or device can't use passkeys. The button is disabled and the password form still works.         |
| Open the AdminCP first         | (Settings → Security) A staff account tried to add a passkey without an AdminCP session in that browser.    |

## For developers [#for-developers]

Error codes (JSON body `{ error }`):

| Status | Code                     | Route                            |
| ------ | ------------------------ | -------------------------------- |
| `400`  | `invalid_challenge`      | `/admin-sign-in`                 |
| `403`  | `verification_failed`    | `/admin-sign-in`                 |
| `403`  | `not_staff`              | `/admin-sign-in`                 |
| `403`  | `admin_session_required` | `/register/options`, `/register` |
| `404`  | `passkeys_disabled`      | all                              |

On the frontend, `useAdminPasskeySignInAction` from `@vitnode/core/tanstack/admin` runs the ceremony, drops the AdminCP identity caches and navigates to the sanitized `returnTo` - the same things the AdminCP password form does. It leaves the public session cache alone, because nothing about the public session changed.

If you registered your own auth transport with `setAuthTransport`, implement `startAdminPasskeySignIn` and `finishAdminPasskeySignIn` as well, and relay cookies on both. The challenge cookie is set by the first call and read by the second, and the second sets the AdminCP cookie. The server-side versions are exported as `startAdminPasskeySignInOnApi` and `finishAdminPasskeySignInOnApi` from `@vitnode/core/tanstack/auth/server`.

# Passkeys (WebAuthn) (/docs/dev/passkeys)

Passkeys let members sign in with their fingerprint, face or screen lock instead of a password. They are built on WebAuthn, can't be phished, and there is nothing to leak - the server only ever stores a **public** key.

VitNode ships passkeys in core. Members add them under **Settings → Security** and use them with **Sign in with a passkey** on `/login`. Staff can use the same passkey on the AdminCP login at `/admin` - see [AdminCP passkey sign-in](/docs/dev/passkeys/admincp). Under the hood it uses [SimpleWebAuthn](https://simplewebauthn.dev) (`@simplewebauthn/server` and `@simplewebauthn/browser`) - the same libraries Better Auth uses - while sessions, users and permissions stay 100% VitNode.

<Callout type="info">
  Looking for the member-facing walkthrough? See [Using
  passkeys](/docs/dev/passkeys/using-passkeys) - it's written so you can link
  your community straight to it.
</Callout>

## Quick start [#quick-start]

Passkeys are **opt-in**: they stay off until you set `authorization.passkeys`. `true` turns them on, with everything derived from `VITNODE_WEB_URL`:

- **origin** - `VITNODE_WEB_URL` itself, e.g. `https://community.example.com`
- **RP ID** - its hostname, e.g. `community.example.com`
- **RP name** - `metadata.shortTitle`, falling back to `metadata.title`

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:3]
  authorization: {
    passkeys: true,
  },
})
```

Need something the defaults can't give you - several origins, or one RP ID shared across subdomains? Pass an object instead, and set only what differs:

```ts title="apps/api/src/vitnode.api.config.ts"
authorization: {
  passkeys: {
    rpId: "example.com",
    origins: ["https://example.com", "https://forum.example.com"],
  },
},
```

Then run the migration (below) and you're done. The login page shows the passkey button as soon as the API reports passkeys as enabled.

## Database migration [#database-migration]

Passkeys add two tables to core:

| Table                           | What's in it                                                                                                                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `core_users_passkeys`           | One row per credential: unique credential ID, COSE public key, signature counter, WebAuthn user handle, transports, device type, backup state, AAGUID, name, timestamps |
| `core_users_passkey_challenges` | Short-lived challenges: a SHA-256 hash of the browser token, the ceremony, the challenge, the user (for registration) and `expiresAt`                                   |

Both reference `core_users` with `ON DELETE CASCADE`. Apply them like any other core migration:

```bash tab="bun"
bun run db:migrate
```

```bash tab="pnpm"
pnpm db:migrate
```

```bash tab="npm"
npm run db:migrate
```

</Tabs>

In development `pnpm dev` runs `vitnode db:prepare`, which applies it for you.

## RP ID, origins and HTTPS [#rp-id-origins-and-https]

A passkey belongs to one **RP ID** (a domain). The browser only offers it on pages whose hostname is that domain or a subdomain of it, and VitNode only accepts responses from the **origins** you list.

- **HTTPS is required**, with one exception: `localhost` (and `*.localhost`) works over plain HTTP, so local development needs no certificates.
- **IP addresses can't be RP IDs.** Open `http://localhost:3000`, not `http://127.0.0.1:3000` - the browser will refuse.
- **Origins are bare**: `https://example.com`, not `https://example.com/` or `https://example.com/login`.
- **Sharing across subdomains**: set `rpId: "example.com"` and list every origin, e.g. `https://example.com` and `https://forum.example.com`.

<Callout type="warn">
  Choose the RP ID before members create passkeys. **Changing it later makes
  every existing passkey unusable** - they are cryptographically bound to the
  old domain. Members would have to sign in another way and add new ones.
</Callout>

VitNode checks the configuration when the API boots:

- A `passkeys` setting that can't work (plain HTTP on a real domain, an RP ID that isn't a parent of an origin, an IP address - including a derived one like `VITNODE_WEB_URL=http://192.168.1.10:3000`) **fails the boot** with a message naming the problem.

Turn passkeys off by removing `passkeys`, or with `passkeys: false`. The **Sign in with a passkey** button disappears from `/login`, the **Security** item disappears from settings (`/settings/security` answers "not found"), and every passkey route answers `404 passkeys_disabled`. Saved passkeys stay in the database, so switching passkeys back on brings them straight back.

## How it works [#how-it-works]

Every ceremony is two requests: **options** (the server issues a challenge) and **verify** (the browser answers it). All routes live under `/api/@vitnode/core/users/passkeys`.

| Method   | Path                | Who                 | Does                                                                                           |
| -------- | ------------------- | ------------------- | ---------------------------------------------------------------------------------------------- |
| `POST`   | `/register/options` | signed-in member    | Issues creation options and a registration challenge bound to this browser **and** this member |
| `POST`   | `/register`         | signed-in member    | Verifies the attestation and saves the passkey                                                 |
| `POST`   | `/sign-in/options`  | anyone              | Issues request options with **no** `allowCredentials`, so the browser offers any saved passkey |
| `POST`   | `/sign-in`          | anyone              | Verifies the assertion and starts a normal session                                             |
| `POST`   | `/admin-sign-in/options` | anyone         | Issues a two-minute, AdminCP-only challenge with `userVerification: "required"`                |
| `POST`   | `/admin-sign-in`    | anyone              | Verifies the assertion, checks staff access live, and starts an **AdminCP** session only       |
| `GET`    | `/`                 | signed-in member    | Lists the member's own passkeys                                                                |
| `PATCH`  | `/{id}`             | the passkey's owner | Renames it                                                                                     |
| `DELETE` | `/{id}`             | the passkey's owner | Removes it - refused with `409 last_recovery_method` if it's the account's last way in         |

From the frontend, call them with the typed fetcher - `module: "users/passkeys"` - like any other core route:

```ts
import { fetcherClient } from "@vitnode/core/lib/fetcher-client"

const res = await fetcherClient({
  plugin: "@vitnode/core",
  method: "get",
  module: "users/passkeys",
  path: "/",
  options: { credentials: "include" },
})
```

### Challenges [#challenges]

- Each options call creates a random token, stores **only its SHA-256 hash** with the challenge, and sets it in an HttpOnly cookie named `<cookieName>_passkey_registration`, `<cookieName>_passkey_authentication` or `<cookieName>_passkey_admin_sign_in` (so `vitnode_auth_passkey_...` by default).
- Challenges expire after **five minutes** - AdminCP sign-in challenges after **two**. Expired rows are swept every time a new ceremony starts.
- Verification consumes the challenge with a single `DELETE ... RETURNING` scoped to the token hash, the ceremony, "not expired" and - for registration - the signed-in user. It's atomic: two concurrent requests with the same cookie can never both win, and a replayed response always fails.
- Because the lookup is by the cookie's token, a challenge can't be used from another browser, by another account, or for another ceremony - a public sign-in challenge never opens the AdminCP, and the other way round.

### Verification [#verification]

The server calls SimpleWebAuthn's `verifyRegistrationResponse` / `verifyAuthenticationResponse` with the stored challenge, your configured `origins` and `rpId`, and `requireUserVerification: true` (options also ask for `userVerification: "required"` and a discoverable credential with `residentKey: "required"`).

On sign-in, the user comes **only** from the stored credential - anything the browser sends besides the WebAuthn response is ignored. If the authenticator returns a user handle, it must match the one saved with that credential.

### Signature counters [#signature-counters]

- Authenticators that always report `0` (most synced passkeys - iCloud Keychain, Google Password Manager) are accepted every time.
- Authenticators with a real counter must go **up**. A counter that stays the same or goes backwards - including dropping back to `0` - is rejected as a possible cloned key.
- The new counter is written with a compare-and-set (`WHERE counter = <previous>`), so two sign-ins racing on one credential can't both succeed.

### Sessions [#sessions]

A successful passkey sign-in calls `SessionModel.createSessionByUserId()` - exactly what password sign-in does - so it sets the usual `vitnode_auth` cookie on the current device. It **never** creates an AdminCP session, even for staff. The AdminCP has its own passkey flow at `/admin` with a separate challenge, a live staff check and its own session - see [AdminCP passkey sign-in](/docs/dev/passkeys/admincp).

Accounts with AdminCP access can only **add** a passkey while an AdminCP session for the same user is open in that browser (`403 admin_session_required` otherwise). Everyone else enrolls as usual.

On the client, `usePasskeySignInAction` clears identity-specific caches (the AdminCP entries, files, devices and passkeys) before navigating, and keeps the `returnTo` destination, just like the password form.

### Keeping members locked in (the good way) [#keeping-members-locked-in-the-good-way]

A member can't remove their **last** passkey unless the account still has a password or a linked SSO provider. A password only counts while [password sign-in](/docs/dev/advanced/auth#turning-off-password-sign-in) is switched on. The check runs in a transaction that locks the user row, so two tabs deleting "one of two" passkeys at once can't leave the account with nothing.

## Events [#events]

| Event                  | Payload                       | Fires when                 |
| ---------------------- | ----------------------------- | -------------------------- |
| `user.passkey.created` | `{ passkeyId, userId }`       | A member adds a passkey    |
| `user.passkey.updated` | `{ passkeyId, userId, name }` | A member renames a passkey |
| `user.passkey.deleted` | `{ passkeyId, userId }`       | A member removes a passkey |

See [Built-in events](/docs/dev/events/built-in-events) for how to listen to them.

## Deployment checklist [#deployment-checklist]

- **Serve the site over HTTPS** on the exact origins you configured. A reverse proxy is fine - what matters is the URL in the member's address bar.
- **Set `VITNODE_WEB_URL`** in every environment, and set `rpId` in the config if you share passkeys across subdomains.
- **Preview deployments** on generated hostnames (e.g. `my-app-git-branch.vercel.app`) are different origins - passkeys created on production won't work there, and a preview needs its own origin in `origins` to register new ones.
- **Separate API server?** Nothing changes: the API checks the _web_ origin the ceremony ran on, not its own URL. Make sure `cookieDomain`/CORS already let the browser send credentialed requests to it.
- **Custom auth transport?** If you registered one with `setAuthTransport`, implement `startPasskeySignIn`, `finishPasskeySignIn`, `startAdminPasskeySignIn` and `finishAdminPasskeySignIn`, and relay cookies on all four - the challenge cookie is set by the first call and read by the second.
- **Rate limiting** - the options routes create a database row per call. Keep the [rate limiter](/docs/dev/advanced/rate-limiter) on in production.

## Troubleshooting [#troubleshooting]

In development, VitNode logs why a ceremony failed (wrong origin, RP ID mismatch, counter error...) to the API console. The browser only ever receives a generic error code.

| You see                                          | Likely cause                                                                                |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| No passkey button on `/login`                    | Passkeys disabled, or the derived config was invalid - check the boot log                   |
| "The RP ID is neither ... nor a parent domain"   | `rpId` doesn't match the hostname of an origin                                              |
| Browser error "invalid domain" / `SecurityError` | The page's hostname isn't the RP ID or a subdomain of it, or the page isn't HTTPS/localhost |
| "That took a little too long"                    | The five-minute challenge expired, or the cookie was blocked - start again                  |
| "Passkey not recognized"                         | The passkey was removed on the site, or it belongs to another RP ID                         |

# Using passkeys (/docs/dev/passkeys/using-passkeys)

A passkey lets you sign in with your fingerprint, your face or your device's screen lock - no password to remember, and nothing a phishing site can steal. It's the same thing your phone already uses to unlock itself, just pointed at this site.

Your passkey is stored on your device or in your password manager (iCloud Keychain, Google Password Manager, 1Password, Bitwarden and friends). The site only ever keeps a public key, which is useless to anyone who gets hold of it.

## Before you start [#before-you-start]

- Use a recent browser: Chrome, Safari, Edge or Firefox.
- Your device needs a screen lock - a PIN, pattern, password, fingerprint or face unlock. A hardware security key with a PIN works too.
- You need to be signed in the usual way to add your first passkey.

## Create a passkey [#create-a-passkey]

1. Sign in with your email and password (or your social login).
2. Open your avatar menu, go to **Settings**, then **Security**.
3. Select **Add a passkey**.
4. Your browser asks you to confirm - use your fingerprint, face, PIN or security key.
5. Done! You'll see "Passkey added", and the new passkey shows up in the list.

The passkey gets a name automatically, like "iCloud Keychain" or "Chrome (Mac OS)". Want something clearer, like "Work laptop"? Select the pencil icon next to it, type a new name and select **Save**.

<Callout type="info">
  If you see "Already set up", this device or password manager already has a
  passkey for your account - you're good to go.
</Callout>

You can add as many passkeys as you like - for example one on your phone and one on your laptop. If your password manager syncs passkeys, one passkey follows you to all your devices; these show a **Synced** badge. Passkeys marked **This device only** live on one device or security key.

## Sign in with a passkey [#sign-in-with-a-passkey]

1. Go to the login page.
2. Select **Sign in with a passkey**. You don't need to type your email.
3. Pick your passkey in the browser prompt and confirm with your fingerprint, face or PIN.

That's it - you'll land wherever you were heading. Signing in on a computer with a passkey that lives on your phone? Most browsers offer a QR code to scan with your phone.

<Callout type="info">
  **On the staff team?** The same passkey signs you in to the AdminCP too. To
  add one, sign in to the AdminCP with your password first, then add the
  passkey from **Settings → Security** in the same browser. See [AdminCP
  passkey sign-in](/docs/dev/passkeys/admincp).
</Callout>

## Remove a passkey [#remove-a-passkey]

1. Go to **Settings → Security**.
2. Select the red bin icon next to the passkey.
3. Confirm with **Remove**.

The site forgets the passkey straight away, so it can't be used to sign in anymore. It may still appear in your password manager - delete it there too to keep things tidy.

<Callout type="warn">
  You can't remove your **last** passkey if it's the only way into your account.
  Add another passkey, or set a password with "Forgot password?" on the login
  page first. This keeps you from accidentally locking yourself out.
</Callout>

## Something went wrong? [#something-went-wrong]

| Message                        | What to do                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------ |
| Passkey sign-in cancelled      | The prompt was closed or timed out. Just try again.                                        |
| That took a little too long    | The request expired after five minutes. Start again.                                       |
| Passkey not recognized         | That passkey was removed or belongs to another site. Try another one or use your password. |
| Passkeys aren't supported here | Your browser or device can't use passkeys. Update your browser or sign in another way.     |
| Passkeys are turned off        | This site has switched passkeys off for now. Use your password or social login.            |

# Performance (/docs/dev/performance)

TanStack Start splits components into separate lazy chunks by default, keeping the initial entry bundle light. Follow these key practices to maintain instant page loads.

## Performance Checklist [#performance-checklist]

1. **Keep `head` metadata isolated**: Never import UI components into route `head`.
2. **Lazy-load heavy dialogs**: Use `React.lazy` + `Suspense` for complex editors and dialogs.
3. **Dynamic imports inside loaders**: Lazy-load heavy server/client utilities with `await import(...)`.
4. **Optimize images**: Use `loading="lazy"`, responsive widths, and explicit dimensions.
5. **Analyze your bundle**: Regularly check client chunk sizes.

---

## What Lands in the Client Entry Bundle [#what-lands-in-the-client-entry-bundle]

TanStack Router automatically extracts route `component`, `errorComponent`, and `notFoundComponent` into lazy chunks:

---

## Best Practices [#best-practices]

### 1. Isolate Metadata from Components [#1-isolate-metadata-from-components]

Because `head` is evaluated in the main route bundle, importing strings from component files accidentally pulls entire component trees into the initial download:

```tsx title="plugins/home/src/pages/home-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

// BAD: Pulls HomeRouteContent and all its heavy icons/charts into main entry
import { HOME_TITLE, HomeRouteContent } from '../views/home-content' // [!code --]

// GOOD: Metadata strings live in a lightweight leaf file
import { HomeRouteContent } from '../views/home-content' // [!code ++]
import { HOME_DESCRIPTION, HOME_TITLE } from '../views/metadata' // [!code ++]

export const route = definePluginRoute({
  head: () =>
    pageHead({
      title: HOME_TITLE,
      description: HOME_DESCRIPTION,
    }),
})

export default HomeRouteContent
```

### 2. Lazy Dialogs and Heavy Form Editors [#2-lazy-dialogs-and-heavy-form-editors]

Heavy editors (like Tiptap) or complex modals should be lazy-loaded with `React.lazy` and `Suspense`:

```tsx title="plugins/blog/src/views/admin/article-editor.tsx"
import React, { Suspense } from 'react'
import { Spinner } from '@vitnode/core/components/ui/spinner'

// [!code ++:6]
const RichEditor = React.lazy(async () =>
  import('@vitnode/core/components/form/fields/editor').then((mod) => ({
    default: mod.AutoFormEditor,
  })),
)

export const ArticleEditor = (props) => (
  <Suspense fallback={<Spinner size="xl" />}>
    <RichEditor {...props} />
  </Suspense>
)
```

### 3. Dynamic Imports Inside Loaders [#3-dynamic-imports-inside-loaders]

When a route loader requires a heavy calculation or parsing library, import it dynamically:

```tsx title="plugins/stats/src/pages/stats-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async () => {
    // Only downloaded when visitor navigates to /stats
    const { calculateStats } = await import('../features/stats/calculator') // [!code ++]
    return calculateStats()
  },
})
```

### 4. Lazy Images Below the Fold [#4-lazy-images-below-the-fold]

Always specify explicit aspect ratios and `loading="lazy"` on images outside the initial viewport, and ship WebP with a `srcSet` so a phone never downloads the desktop rendition:

```tsx
<img
  src={photo.large}
  srcSet={`${photo.small} 800w, ${photo.large} 1600w`}
  sizes="(min-width: 1024px) 1024px, 100vw"
  alt="Community event"
  width={1600}
  height={866}
  loading="lazy"
  decoding="async"
  className="aspect-video object-cover rounded-lg"
/>
```

The one image that is the page's largest element on arrival - a hero screenshot - is the exception: give it `loading="eager"` and `fetchPriority="high"` so the browser asks for it first.

### 5. Skip Rendering Work for Offscreen Sections [#5-skip-rendering-work-for-offscreen-sections]

A long marketing page can carry a hundred CSS animations, most of them below the fold. Give each section `content-visibility: auto` with a `contain-intrinsic-size` estimate and the browser skips style, layout and animation work for everything not near the viewport:

```css title="apps/web/src/site/marketing/marketing.css"
.mk-section-anchor {
  scroll-margin-top: 5rem;
  content-visibility: auto;
  contain-intrinsic-size: auto 48rem;
}
```

The home page went from 133 running animations to 42 on arrival with this one rule, and the pages still scroll and deep-link normally.

### 6. Keep the Plugin Factory Light [#6-keep-the-plugin-factory-light]

`vitnode.config.ts` is bundled with the document shell, so everything a plugin factory imports ships to every visitor. A factory that spreads `admin/content` or `admin/nav` drags the AdminCP editing stack - AutoForm, schemas, dialogs - into the public bundle. Keep it to `pluginId`, `messages` and `routes`; see [Plugin frontend modules](/docs/content-engine/plugin-files).

### 7. Route-Scoped Stylesheets [#7-route-scoped-stylesheets]

Tailwind emits one utility per class it finds in the sources you list. A documentation UI kit scanned globally pays its CSS on the home page too. Give it a stylesheet of its own and load it from the layout route that renders it:

```css title="apps/web/src/docs/docs.css"
@import '../styles.css';
@import 'fumadocs-ui/css/shadcn.css';
@import 'fumadocs-ui/css/preset.css';

@source '../../node_modules/fumadocs-ui/dist/**/*.js';
```

```tsx title="apps/web/src/routes/_docs.tsx"
import docsCss from '@/docs/docs.css?url'

export const Route = createFileRoute('/_docs')({
  loader: async () => ({ pageTree: await getDocsPageTree() }),
  head: () => ({ links: [{ href: docsCss, rel: 'stylesheet' }] }),
  // ...
})
```

A stylesheet a route puts in `head` is a resource React never unloads, so the moment someone opens the docs the page carries both sheets for the rest of the visit - including after they navigate back to the home page. That is fine, on one condition: the route stylesheet has to scan **everything** the app stylesheet scans.

Both sheets are full Tailwind builds emitting into the same `theme, base, components, utilities` layers, and inside one layer the later sheet wins. Let the route stylesheet miss a class and the app stylesheet's version of it loses to whatever the route stylesheet emits last - a missing `sm:block` loses to a plain `hidden`, and the site logo and main navigation quietly vanish from every page after a trip to the docs.

Two things keep the sets aligned: the route stylesheet starts by importing the app one, and `vitNodeTailwindSources` gives both the same `@source` directives for `@vitnode/core` and your configured plugins. Anything you add to the app stylesheet's sources, add for the route stylesheet too.

### 8. Group Shared Vendor Modules [#8-group-shared-vendor-modules]

Rolldown splits every module shared by two routes into its own file, which for an icon library means dozens of 300-byte requests per page. Group the libraries that are shared by design into one chunk each:

```ts title="apps/web/vite.config.ts"
build: {
  rolldownOptions: {
    output: {
      advancedChunks: {
        groups: [
          { name: 'icons', test: /node_modules[\\/].*lucide-react/, minShareCount: 2 },
        ],
      },
    },
  },
},
```

Group only libraries whose shared surface is small. A UI primitive library shared by every AdminCP screen turns into a single 280 KB chunk that public pages then download for a tooltip.

---

## Measuring Bundle Size [#measuring-bundle-size]

Analyze your client bundle with Vite:

```bash tab="bun"
bun run build
```

```bash tab="pnpm"
pnpm build
```

```bash tab="npm"
npm run build
```

</Tabs>

Inspect the output chunk sizes in `apps/web/.output/public/assets/`, then load a page in the browser's network panel and check what the document shell actually requests - a chunk the manifest never preloads can still arrive through a static import. Keep any single lazy chunk below **150 KB** for optimal mobile performance.

## Learn More [#learn-more]

# Dashboard Widgets (/docs/dev/plugins/admin/dashboard-widgets)

Dashboard widgets are **AdminCP plugin extensions**. Define the component and
register it in the same plugin factory that owns the feature; the host dashboard
then discovers it automatically.

{/* Image prompt: VitNode AdminCP dashboard with a “Site notes” statistics widget in a draggable grid. Show the widget panel, the corner resize bracket on each card, and the settings gear. Dark theme, 1600x900. */}

### Build the widget component [#build-the-widget-component]

```tsx title="plugins/site-notes/src/views/admin/widgets/stats-widget.tsx"
import type { AdminDashboardWidgetProps } from '@vitnode/core/lib/plugin'

export const StatsWidget = ({ settings }: AdminDashboardWidgetProps) => (
  <div className="flex flex-col gap-1 p-2">
    <span className="text-muted-foreground text-sm">Published notes</span>
    <strong className="text-3xl tabular-nums">
      {String(settings.total ?? 42)}
    </strong>
  </div>
)
```

</Step>
  <Step>

### Register it in the existing plugin factory [#register-it-in-the-existing-plugin-factory]

```tsx title="plugins/site-notes/src/config.tsx"
import { BarChart3Icon } from 'lucide-react'

import { StatsWidget } from './views/admin/widgets/stats-widget'

export const siteNotesPlugin = () =>
  buildPlugin({
    admin: {
      dashboard: {
        widgets: [
          // [!code ++:9]
          {
            component: StatsWidget,
            defaultEnabled: true,
            defaultRows: 1,
            defaultSpan: 1,
            icon: <BarChart3Icon />,
            id: 'stats',
          },
        ],
      },
    },
    messages,
    pluginId: '@acme/site-notes',
    routes,
  })
```

The full widget id is namespaced by the plugin, so `stats` will not collide with
another plugin’s idea of a stats card. A good thing—statistics are dramatic
enough already.

</Step>
  <Step>

### Add a permission or settings UI when needed [#add-a-permission-or-settings-ui-when-needed]

Add `permission` to hide a widget from staff who should not see it. Add
`settingsComponent` when administrators need to save preferences; both stay in
the plugin alongside the widget.

```tsx title="plugins/site-notes/src/config.tsx"
{
  component: StatsWidget,
  // [!code ++:4]
  permission: { module: 'site_notes', permission: 'can_view_stats' },
  settingsComponent: StatsSettings,
  id: 'stats',
}
```

</Step>
</Steps>

## Widget options [#widget-options]

| Option                        | What it controls                                  |
| ----------------------------- | ------------------------------------------------- |
| `defaultSpan` / `defaultRows` | Initial grid size from 1 to 3 columns or rows.    |
| `minSpan`                     | Narrowest allowed width.                          |
| `defaultEnabled`              | Whether a new dashboard receives the widget.      |
| `allowMultiple`               | Whether an admin may place more than one copy.    |
| `permission`                  | Staff permission required to see the widget.      |
| `settingsComponent`           | Plugin form shown in the widget's panel while the dashboard is being edited. |

## How admins arrange them [#how-admins-arrange-them]

Your widget does not need any code for this - it is what the dashboard does with every widget. Press **Edit layout** and the **Widgets** panel slides in beside the grid.

| To…                    | Do this                                                                                                                                  |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| **Add a widget**       | Click it in the panel to put it at the end, or drag it onto the grid. While you drag, the grid opens a gap the widget's real size, right where it will land. |
| **Change your mind**   | Drag it back over the panel and let go. Nothing is added, and the card glides back to where it came from.                                  |
| **Move a widget**      | Drag the card from anywhere on it, or <kbd>Tab</kbd> to it and use Space and the arrow keys. The spot it came from turns into a dashed slot. |
| **Resize a widget**    | Grab the little bracket in the card's bottom corner and pull. Sideways snaps the width between 1 and 3 columns, down and up snap the height between 1 and 3 rows, and the other widgets glide out of the way. A dashed outline follows your pointer so you can see where you are pulling. From the keyboard, <kbd>Tab</kbd> to the corner and use the arrow keys. |
| **Edit a widget**      | Click the card (or <kbd>Tab</kbd> to it and press <kbd>Enter</kbd>). The panel switches to that widget: a width switch, its own settings form if it has one, and a bin in the header. **Save settings** stores the settings straight away and leaves the rest of your unsaved arrangement alone. The arrow at the top goes back to the list. |
| **Remove a widget**    | The bin on the card's toolbar, or in its panel. |
| **Finish**             | The panel footer says whether anything changed. **Save** keeps the arrangement; **Cancel** throws it away and leaves edit mode. |

New widgets fade in and scroll into view, and screen readers hear where a widget was picked up and dropped in the admin's own language. With _reduce motion_ turned on in the operating system, all of it happens instantly.

The drop gap uses `defaultSpan` and `defaultRows`, so pick them to match what the widget looks like the moment it is added.

<Cards>
  <Card
    icon={<Settings2Icon />}
    title="AdminCP pages"
    description="Add plugin-owned routes and browser-safe sidebar navigation."
    href="/docs/dev/plugins/admin"
  />
  <Card
    icon={<BarChart3Icon />}
    title="Staff permissions"
    description="Define permissions before exposing staff-only capabilities."
    href="/docs/dev/working-with-users/staff-permissions"
  />
</Cards>

# AdminCP Pages (/docs/dev/plugins/admin)

AdminCP is a plugin surface. Give the plugin an `area: 'admin'` route and a
browser-safe navigation declaration. The host supplies the panel shell; your
plugin supplies the useful bit.

### Claim an AdminCP route [#claim-an-admincp-route]

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  // [!code ++:4]
  page('/admin/site-notes/settings', {
    area: 'admin',
    component: lazy(() => import('./pages/admin-settings-page')),
  }),
])
```

</Step>
  <Step>

### Render the plugin page [#render-the-plugin-page]

```tsx title="plugins/site-notes/src/pages/admin-settings-page.tsx"
const AdminSettingsPage = () => (
  <div className="flex flex-col gap-2 p-4">
    <h2 className="text-2xl font-semibold">Site notes settings</h2>
    <p className="text-muted-foreground">Manage the notes plugin.</p>
  </div>
)

export default AdminSettingsPage
```

</Step>
  <Step>

### Add a sidebar entry [#add-a-sidebar-entry]

Export `adminNav` from the plugin. Its small browser-safe shape is what the
generated AdminCP registry imports—do not edit `admin-nav.gen.ts` yourself.

```tsx title="plugins/site-notes/src/admin/nav.tsx"
import type { AdminNavPluginSource } from '@vitnode/core/lib/plugin'
import { SettingsIcon } from 'lucide-react'

export const adminNav = {
  pluginId: '@acme/site-notes',
  admin: {
    nav: [
      // [!code ++:6]
      {
        href: '/admin/site-notes/settings',
        icon: <SettingsIcon />,
        id: 'settings',
        permission: { module: 'site_notes', permission: 'can_manage_settings' },
      },
    ],
  },
} satisfies AdminNavPluginSource
```

The generator’s `./*` package export already exposes `admin/nav`; no manual
`package.json` export is required, and nothing changes in `config.tsx`. The
generated `admin-nav.gen.ts` imports `admin/nav` directly, and keeping the
factory to plain data is what keeps the sidebar registration out of every
public page's bundle.

</Step>
  <Step>

### Verify the screen [#verify-the-screen]

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

Visit `http://localhost:3000/admin/site-notes/settings` as a staff account with
the declared permission.

{/* Image prompt: VitNode AdminCP settings page contributed by a plugin. Show the existing admin sidebar with “Site notes” selected, a compact settings screen, breadcrumb, and staff-permission badge. Dark theme, 1440x900. */}

</Step>
</Steps>

## Extend the panel [#extend-the-panel]

<Cards>
  <Card
    icon={<LayoutDashboardIcon />}
    title="Dashboard widgets"
    description="Add a plugin widget to the admin dashboard’s configurable grid."
    href="/docs/dev/plugins/admin/dashboard-widgets"
  />
  <Card
    icon={<ShieldCheckIcon />}
    title="Staff permissions"
    description="Define the permissions that gate staff actions and navigation."
    href="/docs/dev/working-with-users/staff-permissions"
  />
  <Card
    icon={<RouteIcon />}
    title="Plugin routes"
    description="Configure route areas, namespaces, guards, and parameters."
    href="/docs/dev/routing"
  />
</Cards>

# API Modules (/docs/dev/plugins/api/modules)

Start with [a plugin](/docs/dev/plugins/create), not a host endpoint. A module
groups the plugin's Hono routes under one URL prefix and gives OpenAPI a tidy
place to describe them.

<Callout type="info" title="A generated plugin already has one">
  `create-vitnode-app --plugin` writes a `hello` module, its `config.api.ts` and
  a page that calls it. Read on for what each piece does—then rename them, or add
  a second module beside them.
</Callout>

{/* Image prompt: Dark-theme API ownership diagram. A Site notes plugin contains a Hono route, notes module, and config.api file; the app API configuration composes the plugin once. Show resulting GET endpoint, 1600x900. */}

### Define one plugin endpoint [#define-one-plugin-endpoint]

```ts title="plugins/site-notes/src/api/modules/notes/list.route.ts"
import { z } from '@hono/zod-openapi'
import { buildRoute } from '@vitnode/core/api/lib/route'

export const listNotesRoute = buildRoute({
  pluginId: '@acme/site-notes',
  route: {
    method: 'get',
    path: '/',
    responses: {
      // [!code ++:7]
      200: {
        content: {
          'application/json': {
            schema: z.object({ notes: z.array(z.string()) }),
          },
        },
        description: 'Published site notes.',
      },
    },
  },
  handler: (c) => c.json({ notes: ['Hello plugin'] }),
})
```

</Step>
  <Step>

### Group it and export the plugin API [#group-it-and-export-the-plugin-api]

```ts title="plugins/site-notes/src/api/modules/notes/notes.module.ts"
import { buildModule } from '@vitnode/core/api/lib/module'

import { listNotesRoute } from './list.route'

export const notesModule = buildModule({
  name: 'notes',
  pluginId: '@acme/site-notes',
  routes: [listNotesRoute], // [!code ++]
})
```

```ts title="plugins/site-notes/src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { notesModule } from './api/modules/notes/notes.module'

export const siteNotesApiPlugin = () =>
  buildApiPlugin({
    modules: [notesModule], // [!code ++]
    pluginId: '@acme/site-notes',
  })
```

This file, and not `config.tsx`: the API config reaches your handlers, database
and secrets, while `config.tsx` is read by the browser build. A module
registered in the wrong one is shipped to every visitor.

`buildApiPlugin` keeps everything it was given as a literal type - the plugin
id, the tuple of modules, and every module nested inside them. That type is
what the [fetcher](/docs/dev/fetcher) infers routes from, so a route you add
here is callable, and checked, the moment you save.

</Step>
  <Step>

### Export the type an application registers [#export-the-type-an-application-registers]

Your pages call the endpoint through the universal fetcher, and the fetcher
looks the plugin up in the API plugin registry. Export one reduced type beside
your factory - `create-vitnode-app --plugin` writes this for you:

```ts title="plugins/site-notes/src/config.api.ts"
import type { ApiPluginContract } from '@vitnode/core/api/lib/plugin'

import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

export const siteNotesApiPlugin = () =>
  buildApiPlugin({ modules: [notesModule], pluginId: '@acme/site-notes' })

// [!code ++:3]
export type VitNodeApiPlugin = ApiPluginContract<
  ReturnType<typeof siteNotesApiPlugin>
>
```

`ApiPluginContract` keeps the four things a call needs - the literal plugin id,
every module path you serve, your module tree and your route definitions - and
drops everything else. Your Hono application, content models, event listeners,
queue tasks, WebSockets, search indexers and messages are runtime concerns, so
an app that installs your plugin never resolves them to type-check a call.

`import type` is the whole point: the factory is never executed here, so none of
the Hono, database or secret code behind it is ever reached by a browser build.

<Callout type="warn" title="A plugin never registers itself">
  Your package augments nothing. The app that installs you writes the entry into
  its own generated `src/api-registry.gen.ts`, from the plugins it configured. A
  package that registered itself would put its routes into the registry of every
  project that merely installed it.

To type-check your own pages before any app has installed the plugin, the
  scaffold writes `test-fixtures/api-registry.d.ts` - the same entry an app
  generates, kept outside `src` and out of the published package.
</Callout>

</Step>
  <Step>

### Compose it in the app API config [#compose-it-in-the-app-api-config]

The app decides which installed plugins are active. Add the factory to the Hono
config that serves your app (`apps/web` for a single app, or `apps/api` when it
is separate):

```ts title="apps/web/src/vitnode.api.config.ts"
import { siteNotesApiPlugin } from '@acme/site-notes/config.api' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  plugins: [siteNotesApiPlugin()], // [!code ++]
})
```

The endpoint is now `GET /api/@acme/site-notes/notes`. OpenAPI picks it up too;
one less hand-written map to maintain. This is the one place `siteNotesApiPlugin()`
is ever called - everywhere else it is a type.

</Step>
  <Step>

### Call it [#call-it]

```ts title="plugins/site-notes/src/features/notes/notes-query.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'

const response = await fetcher({
  plugin: '@acme/site-notes', // [!code ++]
  method: 'get',
  module: 'notes',
  path: '/',
})

const { notes } = await response.json()
```

Nothing but the plugin id crosses into the browser bundle. `module`, `path`,
`method` and the response are inferred from the module tree registered above,
and a typo in any of them is a compile error.

</Step>
</Steps>

<Cards>
  <Card
    icon={<RouteIcon />}
    title="Validate inputs"
    description="Use Zod schemas for params, queries, request bodies, and typed responses."
    href="/docs/dev/plugins/api/routes"
  />
  <Card
    icon={<ShieldCheckIcon />}
    title="Protect staff APIs"
    description="Require a staff permission before an AdminCP action reaches its handler."
    href="/docs/dev/working-with-users/staff-permissions"
  />
  <Card
    icon={<NetworkIcon />}
    title="Call the API"
    description="Use VitNode's typed fetcher from a plugin-owned page or component."
    href="/docs/dev/fetcher"
  />
</Cards>

# API Routes (/docs/dev/plugins/api/routes)

Create [the plugin](/docs/dev/plugins/create) and its [API module](/docs/dev/plugins/api/modules)
first. Then put the endpoint in that module so its validation, permission, and
OpenAPI record travel together.

### Validate input and response [#validate-input-and-response]

```ts title="plugins/site-notes/src/api/modules/notes/get.route.ts"
import { z } from '@hono/zod-openapi'
import { buildRoute } from '@vitnode/core/api/lib/route'

export const getNoteRoute = buildRoute({
  pluginId: '@acme/site-notes',
  route: {
    method: 'get',
    path: '/{id}',
    request: {
      params: z.object({ id: z.coerce.number().int().positive() }),
    },
    responses: {
      // [!code ++:7]
      200: {
        content: {
          'application/json': {
            schema: z.object({ id: z.number(), title: z.string() }),
          },
        },
        description: 'One site note.',
      },
    },
  },
  handler: (c) => {
    const { id } = c.req.valid('param')
    return c.json({ id, title: 'Plugin-owned note' })
  },
})
```

</Step>
  <Step>

### Gate an AdminCP action [#gate-an-admincp-action]

Add `adminStaffPermission` to an action that only staff should call. The API
still authorizes server-side; a hidden button is merely good manners.

```ts title="plugins/site-notes/src/api/modules/notes/publish.route.ts"
import { z } from '@hono/zod-openapi'
import { buildRoute } from '@vitnode/core/api/lib/route'

export const publishNoteRoute = buildRoute({
  // [!code ++:13]
  adminStaffPermission: {
    module: 'site_notes',
    permission: 'can_publish',
  },
  pluginId: '@acme/site-notes',
  route: {
    method: 'post',
    path: '/{id}/publish',
    responses: {
      200: {
        content: {
          'application/json': {
            schema: z.object({ published: z.literal(true) }),
          },
        },
        description: 'The note was published.',
      },
    },
  },
  handler: async (c) => c.json({ published: true }),
})
```

</Step>
</Steps>

{/* Image prompt: Dark-theme API documentation screenshot. Show an OpenAPI endpoint for a plugin route with path parameter validation, a successful JSON response, and a staff-permission lock badge. 1440x900. */}

<Callout type="idea" title="One route, one plugin owner">
  Keep handlers with the feature that owns the data. The host API config only
  composes plugins; it should not become a surprise sequel to your business
  logic.
</Callout>

<Cards>
  <Card
    icon={<BoxIcon />}
    title="API modules"
    description="Register a module and its plugin API factory with the Hono application."
    href="/docs/dev/plugins/api/modules"
  />
  <Card
    icon={<ShieldCheckIcon />}
    title="Staff permissions"
    description="Define the permission catalog that gates AdminCP actions."
    href="/docs/dev/working-with-users/staff-permissions"
  />
  <Card
    icon={<ZapIcon />}
    title="Typed fetcher"
    description="Call validated plugin endpoints from the TanStack Start UI."
    href="/docs/dev/fetcher"
  />
</Cards>

# Build and watch a plugin (/docs/dev/plugins/build)

`vitnode build` turns a plugin's `src` folder into `dist/src`: one JavaScript file, one declaration file (`.d.ts`) and one declaration map per module. `vitnode dev` does the same in watch mode, so an app using the plugin reloads as you save. There is no build config to write. VitNode owns it, and every plugin and adapter package is built the same way.

## What tsdown does [#what-tsdown-does]

[tsdown](https://tsdown.dev) is the compiler behind both commands. It runs in **unbundle mode**: every module is compiled on its own instead of being merged into one bundle, so `src/pages/home-page.tsx` becomes `dist/src/pages/home-page.js`.

Every `.ts` and `.tsx` file under `src` is compiled, not only what an `index.ts` imports, because the plugin's `"./*"` export makes each module public. Test files (`*.test.ts`, `*.test.tsx`, `*.test-d.ts`), `src/tests/`, `__tests__/` and `__fixtures__/` folders stay out of `dist`.

The output is ES modules that Node and Vite load as they are:

- **Imports of packages stay imports.** React, Hono, Drizzle, `@vitnode/core` and every other package are left for the app to install, exactly as written.
- **Relative imports get their `.js` extension**, and dynamic imports such as `lazy(() => import("./pages/home-page"))` keep working.
- **`@/` aliases become relative paths**, in the JavaScript and in the declarations. The aliases come from `paths` in `tsconfig.build.json`.
- **JSX** uses React's automatic runtime (`react/jsx-runtime`).
- **File names are kept**, so `auth.server.ts` stays `auth.server.js`. Modules keep their side effects; nothing is tree-shaken away.

A production build is minified and ships declaration maps, but no JavaScript source maps. `vitnode dev` writes readable JavaScript with source maps instead.

## Assets and aliases [#assets-and-aliases]

Every file under `src` that is not code (locale JSON, CSS, images for emails) is copied to the same place under `dist/src`. Imports of those files stay imports, with their import attributes:

```ts title="src/locales/index.ts"
export default {
  en: async () => await import("./en.json", { with: { type: "json" } }),
};
```

`dist/src/locales/index.js` imports `./en.json` next to it, so the compiled module finds its JSON the way the source did. An app loads your translations through the `"./locales/*.json"` export instead, which points at `src/locales`.

## Types and declarations [#types-and-declarations]

Two TypeScript jobs run side by side, and both must pass:

| Job            | What it does                                                                   |
| -------------- | ------------------------------------------------------------------------------ |
| tsdown         | Writes the `.d.ts` files and their maps with the TypeScript compiler           |
| `tsc --noEmit` | Type checks the whole package with `tsconfig.build.json` and fails on an error |

Declarations are written from every file `tsconfig.build.json` includes. That matters for files nothing imports, such as `global.d.ts` and the generated `types/api-registry.gen.d.ts`: they are what lets `fetcher({ plugin: "@acme/site-notes", ... })` infer its response, and that inferred type lands in your `.d.ts` files.

You don't need `isolatedDeclarations` or explicit return types. Inferred types come out the same as `tsc` would write them.

## What a plugin package needs [#what-a-plugin-package-needs]

| File                  | Why                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------- |
| `package.json`        | `"type": "module"`, `exports` pointing into `./dist/src/`, and `tsdown` and `typescript` in `devDependencies` |
| `tsconfig.json`       | Compiler options for your editor, with `"paths": { "@/*": ["./src/*"] }`                |
| `tsconfig.build.json` | The same, without tests: what `vitnode build` compiles and type checks                  |

The CLI treats a folder as a plugin package when it has `tsconfig.build.json` and its `exports` point into `./dist/src/`. `create-vitnode-app` generates all three files. A `tsdown.config.ts` in a plugin is not read.

## How `vitnode dev` watches a plugin [#how-vitnode-dev-watches-a-plugin]

`vitnode dev` runs three watchers:

- **tsdown js** rebuilds the JavaScript and copies changed assets, usually within 100 ms for a plugin.
- **tsdown types** rebuilds the declarations once TypeScript has caught up, a few seconds later.
- **`tsc --watch --noEmit`** prints type errors.

The two tsdown watchers run as separate processes, so the TypeScript compiler never holds back the JavaScript your app reloads.

Adding, deleting or renaming a file restarts both tsdown watchers with the new list of modules, after a short pause so a branch switch counts as one change. Output for a deleted module is removed from `dist/src`. A file that fails to compile is reported, the last good output stays in place, and the next save rebuilds.

<kbd>Ctrl</kbd>+<kbd>C</kbd> stops every watcher. If one of them exits on its own, the CLI stops the rest and exits with an error.

## How dist stays consistent [#how-dist-stays-consistent]

A build only writes to `dist/src`, and only files whose content changed. An app watching the plugin reloads for the module you edited, not for every file in the package. After a successful build, files under `dist/src` that no source produces anymore are deleted. Nothing outside `dist/src` is touched, so don't keep hand-written files in `dist/src`.

Writes are not atomic. A changed file is overwritten in place, so for a moment an app's dev server can see the old or a partly written file, and may reload once more when the write finishes. Since only changed files are written, this window covers the files you edited.

## Plugin, CLI and app builds [#plugin-cli-and-app-builds]

VitNode uses different builds for different things. This page is about the first one.

| Build          | Who runs it                        | Tool                                                        |
| -------------- | ---------------------------------- | ----------------------------------------------------------- |
| Plugin package | `vitnode build` in a plugin        | tsdown in unbundle mode, plus `tsc --noEmit`                |
| VitNode CLI    | `pnpm build:scripts` in `@vitnode/core` | tsdown with `packages/vitnode/tsdown.config.ts`, into `dist/scripts` |
| App            | `vitnode build` in an app          | Vite and TanStack Start, unchanged                          |

`@vitnode/core` itself is built as a plugin package into `dist/src`. Its CLI build writes `dist/scripts` and only cleans that folder, so the two never delete each other's output.

## Limitations [#limitations]

- tsdown needs Node.js `^22.18.0`, `^24.11.0` or `26` and later, which is also the range VitNode supports. Node.js 23 and 25 are not on the list.
- Declarations are generated by the TypeScript compiler, which is the slow part of a build. In watch mode they arrive a few seconds after the JavaScript. For a package as large as `@vitnode/core`, adding or deleting a file rebuilds all of its declarations.
- Each JavaScript rebuild renders every module of the package again and writes only the changed ones. That takes under 100 ms for a typical plugin and about 2 seconds for the roughly 1,600 modules of `@vitnode/core`.
- A re-export-only `index.ts` may get no `.d.ts.map`, so "Go to definition" stops at its `.d.ts` first.

## Next steps [#next-steps]

# Create a Plugin (/docs/dev/plugins/create)

A plugin is the starting point for a VitNode feature. It keeps routes, API
modules, data, translations, and AdminCP extensions together in one installable
package. Nice boundaries; fewer archaeological digs later.

<Callout type="warn" title="Plugins need a workspace">
  Run the generator from a repository with `turbo.json`. When creating an app,
  turn on Turborepo first; a plain single-folder app has nowhere for
  `plugins/*`.
</Callout>

### Generate the package [#generate-the-package]

Run this at the workspace root and enter a package name such as
`@acme/site-notes` when prompted:

```bash tab="bun"
bun create vitnode-app@canary --plugin
```

```bash tab="pnpm"
pnpm create vitnode-app@canary --plugin
```

```bash tab="npm"
npm create vitnode-app@canary -- --plugin
```

</Tabs>

</Step>
  <Step>

### Run/Restart it and visit the route [#runrestart-it-and-visit-the-route]

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

</Step>
  <Step>

### Check the generated page [#check-the-generated-page]

Visit the route printed in the console, such as `http://localhost:3000/site-notes`. You should see a page with a title and a link to the plugin's README.

</Step>
</Steps>

## What gets generated [#what-gets-generated]

One page at `/site-notes` whose loader calls the plugin's own `hello` endpoint, its strings, and a Vitest test for the endpoint (`pnpm test` in the plugin). The generator also registers the plugin in your apps' `vitnode.config.ts` and `vitnode.api.config.ts`, installs it and builds it.

The plugin name must be a valid npm name and must not be one of core's routes: `admin`, `api`, `core`, `discover`, `files`, `login`, `notifications`, `register`, `search`, `users` or `vitnode`.

Check the result the way your app will load it:

```bash
vitnode plugin validate site-notes
```

See [Plugin CLI](/docs/dev/cli/plugins) for what validation checks.

## Add the next capability [#add-the-next-capability]

<Cards>
  <Card
    icon={<RouteIcon />}
    title="Plugin routes"
    description="Add nested layouts, dynamic URLs, loaders, metadata, and guards."
    href="/docs/dev/routing"
  />
  <Card
    icon={<BoxIcon />}
    title="API modules"
    description="Add another endpoint beside the generated one, with Zod-validated inputs."
    href="/docs/dev/plugins/api/modules"
  />
  <Card
    icon={<DatabaseIcon />}
    title="Database models"
    description="Put Drizzle models and migrations beside the feature that owns them."
    href="/docs/dev/database"
  />
  <Card
    icon={<LayoutDashboardIcon />}
    title="Admin Control Panel"
    description="Ship staff screens, navigation, permissions, and dashboard widgets."
    href="/docs/dev/plugins/admin"
  />
</Cards>

# Migrate a plugin from SWC to tsdown (/docs/dev/plugins/migrate-to-tsdown)

Plugins generated before the switch to tsdown compiled with `tsc`, SWC and `tsc-alias`. `vitnode build` and `vitnode dev` no longer run those tools, so an older plugin needs `tsdown` instead. Your sources, exports and import paths stay the same, and the migration takes about five minutes.

### Swap the build dependencies [#swap-the-build-dependencies]

In the plugin's folder, remove SWC and `tsc-alias`, then add tsdown:

```bash tab="bun"
bun remove @swc/cli @swc/core tsc-alias
bun add -D tsdown
```

```bash tab="pnpm"
pnpm remove @swc/cli @swc/core tsc-alias
pnpm add -D tsdown
```

```bash tab="npm"
npm uninstall @swc/cli @swc/core tsc-alias
npm i -D tsdown
```

</Tabs>

Keep `typescript`: the build still uses it for declarations and type checking. If a standalone API app in your workspace builds with `tsc-alias`, keep it there. Only plugin packages switched.

</Step>
  <Step>

### Delete `.swcrc` [#delete-swcrc]

Delete `.swcrc` from the plugin, and the `/.swcrc` line from its `.npmignore`. VitNode owns the build configuration, so there is nothing to replace it with.

</Step>
  <Step>

### Check `package.json` [#check-packagejson]

The scripts should call the CLI, and `exports` should point into `./dist/src/`, which is how the CLI recognizes a plugin package now that `.swcrc` is gone:

```json title="package.json"
{
  "type": "module",
  "scripts": {
    "build:plugins": "vitnode build",
    "dev": "vitnode dev"
  },
  "exports": {
    "./locales/*.json": "./src/locales/*.json",
    "./*": {
      "import": "./dist/src/*.js",
      "types": "./dist/src/*.d.ts",
      "default": "./dist/src/*.js"
    }
  }
}
```

If your scripts still run `tsc`, `swc` and `tsc-alias` directly, replace them with these two.

</Step>
  <Step>

### Build the plugin [#build-the-plugin]

```bash tab="bun"
bun run build:plugins
```

```bash tab="pnpm"
pnpm build:plugins
```

```bash tab="npm"
npm run build:plugins
```

</Tabs>

The first build removes leftovers from the old build that no source produces anymore, such as a stray `dist/vitest.config.d.ts`. Files outside `dist/src` are not touched.

</Step>
</Steps>

## Check the result [#check-the-result]

Validate the plugin from the app that uses it, through the same loaders the app runs:

```bash
vitnode plugin validate <plugin-name>
```

`dist/src` holds one `.js`, `.d.ts` and `.d.ts.map` per module, plus copies of your JSON and CSS. Then start `vitnode dev` in the plugin and save a file: the app reloads with the change.

## Troubleshooting [#troubleshooting]

| Message                                                    | Fix                                                                                    |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `... is not a VitNode app, API or plugin package.`         | Add `tsconfig.build.json`, or point `exports` into `./dist/src/`                        |
| `Could not find "tsdown" from ...`                         | Install `tsdown` in the plugin as shown in the first step                              |
| `Build failed: tsc exited with code 2`                     | A type error. The build prints it; the old build failed on it too                      |
| A file you put in `dist/src` by hand disappears            | Move it to `src`. Non-code files there are copied to `dist/src` on every build        |

[Build and watch a plugin](/docs/dev/plugins/build) explains what the new build does with each file.

# Main Navigation (/docs/dev/plugins/navigation)

The links in the site header are not hard-coded. Administrators build the menu
in **AdminCP → Core → System → Navigation**, and every item there is one of two
things:

- a **prebuilt page** - a destination a plugin declared, so the admin picks it
  from a list and never types a URL;
- a **custom link** - any address, on this site or elsewhere.

Both carry a title and a description in every enabled language, can open in a
new tab, can be dragged into any order, and can be tucked one level under
another item to form a dropdown. Your plugin's job is small: tell VitNode which
of its pages are worth a spot in the menu.

## Offer a prebuilt page [#offer-a-prebuilt-page]

### Declare the preset [#declare-the-preset]

Add a `navigation` array to the plugin's API config. An `id` and an `href` are
all a preset needs; `isOpenInNewTab` is optional and off by default.

```ts title="plugins/site-notes/src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

export const siteNotesApiPlugin = () =>
  buildApiPlugin({
    pluginId: '@acme/site-notes',
    // [!code ++:9]
    navigation: [
      { href: '/notes', icon: 'notebook-pen', id: 'notes' },
      {
        href: 'https://status.acme.dev',
        icon: 'activity',
        id: 'status',
        isOpenInNewTab: true,
      },
    ],
    modules: [],
  })
```

The `id` is lowercase letters, digits, `-` and `_`. The `href` starts with `/`
for a page on this site or with `https://` for anything else - plaintext
`http://` is refused, for presets and for what an administrator types. The
optional
`icon` is a [lucide](https://lucide.dev/icons) name in kebab-case, such as
`notebook-pen`. VitNode refuses a preset that breaks any of those rules at boot,
with a message naming the plugin, so a typo never reaches an administrator.

</Step>
  <Step>

### Name it in the locale file [#name-it-in-the-locale-file]

The default title and description live under `navigation.<id>` in the plugin's
own message tree. That is what the admin sees in the picker and what visitors
see in the header until an admin overrides it.

```json title="plugins/site-notes/src/locales/en.json"
{
  "@acme/site-notes": {
    // [!code ++:6]
    "navigation": {
      "notes": {
        "title": "Notes",
        "description": "Short posts from the team."
      }
    }
  }
}
```

`description` is optional. A preset with no title in any language is skipped by
the header rather than shown as a raw key, so this step is not decorative.

</Step>
  <Step>

### Add it to the menu [#add-it-to-the-menu]

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

Open **AdminCP → Core → System → Navigation**, click **Add menu item** and
pick the *Notes* tile under **Pages from your plugins**. Tweak the title or
icon if you like, then **Add to menu**. It appears in the header immediately.

{/* Image prompt: VitNode AdminCP "Navigation" screen. One rounded card listing menu items as compact one-line rows: a grip handle, a lucide icon, a title, a monospace URL on the right, the plugin name or "Custom", and a "⋯" button; child rows are indented behind a thin vertical guide line under their parent, and the card header reads "3 in the header · 4 in dropdowns" with a "Collapse all" button. An "Add menu item" dialog is open in front, showing "Pages from your plugins" as a grid of tiles (icon, page name, plugin name) and a wide "Custom link" tile below. Clean light theme, 1440x900. */}

</Step>
</Steps>

## What administrators can change [#what-administrators-can-change]

| Setting              | Prebuilt page                                     | Custom link |
| -------------------- | ------------------------------------------------- | ----------- |
| Title, description   | Optional override per language, defaults to yours | Required    |
| URL                  | Always the plugin's `href`, even after it changes | Any `/path` or `https://` address |
| Icon                 | Yours by default, replaceable                     | Optional    |
| Open in a new tab    | Yes                                               | Yes         |
| Order                | Drag and drop                                     | Drag and drop |
| Nesting              | One level, as a dropdown                          | One level, as a dropdown |

### Icons [#icons]

Every menu item can carry a lucide icon, picked from the same picker a role
prefix uses, restricted to its icon half - no emoji. A prebuilt item starts on
the icon its plugin declared and the picker opens on it; the remove button on
the field goes back to that default rather than storing a blank. Icons are
stored as `icon:<name>` and drawn server-side, exactly like a role's prefix.

### Order and dropdowns [#order-and-dropdowns]

Every item in the list has a grip handle. Drag it up or down to reorder, or drop
it a little to the **right** to nest it under the item above. The menu is one
level deep on purpose: a header dropdown with sub-dropdowns is a maze, not a
menu, so an item that already has children stays at the top level and nothing
can be dropped under a child.

While you drag, a dashed slot shows exactly where the item will land - shifted
right when it is about to go inside the item above.

Keyboard works too: focus a handle, press <kbd>Space</kbd>, move with the arrow
keys - <kbd>→</kbd> nests, <kbd>←</kbd> un-nests - and press <kbd>Space</kbd>
again to drop.

Not a fan of dragging? Every row has a **⋯** menu with **Move up**, **Move
down**, **Move inside…** and **Move to top level**, plus **Add sub-item** on
top-level rows, which opens the add dialog already aimed at that dropdown.
Clicking a row opens its editor on the side, where **Placement** does the same
job as dragging it sideways. Long menus fold up too: the arrow next to a parent
hides its dropdown, and **Collapse all** tidies the whole list.

A top-level item with children renders in the header as a **dropdown**: the
parent opens it on hover and still follows its own URL when clicked, and its
children are the links, each with its description under the label. Remove a
parent and its children move back to the top level rather than disappearing.

Because a preset item stores only `pluginId` and `id`, moving a route in your
plugin moves every menu that links to it. Uninstalling the plugin hides its
items from the header and flags them in the AdminCP list, without deleting the
admin's titles - reinstall the plugin and they are back.

## How the header gets the menu [#how-the-header-gets-the-menu]

The menu ships inside the middleware endpoint every page already reads, next to
the SSO and captcha configuration:

```ts
const response = await fetcher({
  plugin: '@vitnode/core',
  method: 'get',
  module: 'middleware',
  path: '/',
})

const { navigation } = await response.json()
```

Each top-level entry carries the resolved `href`, `icon`, `isOpenInNewTab`, the
stored `title` and `description` overrides for every language, and an `items`
array with the same shape for its dropdown. Preset defaults are
translated in the browser from the plugin's `navigation` namespace, which the
header warms for exactly the plugins whose presets are in the menu.

On the server the menu is cached for a day (`c.get("cache")`, Redis when
`REDIS_URL` is set) and expired the moment an administrator saves a change, so
"long cache" and "instant updates" are not in tension. Without Redis it is one
small query per request.

## Permissions [#permissions]

Everything under **Navigation** is gated by the core `navigation` staff module:

| Permission   | Lets an administrator            |
| ------------ | -------------------------------- |
| `can_view`   | Open the screen and see the list |
| `can_create` | Add items                        |
| `can_edit`   | Edit and reorder items           |
| `can_delete` | Remove items                     |

Grant them per role or per admin under **Staff → Administrators**, like any
other [staff permission](/docs/dev/working-with-users/staff-permissions).

## Events [#events]

Every change emits a [built-in event](/docs/dev/events/built-in-events#navigation-events):
`navigation.created`, `navigation.updated`, `navigation.reordered` and
`navigation.deleted`. Listen to them to purge a CDN or keep an audit trail.

## Next [#next]

# Breadcrumbs (/docs/dev/routing/breadcrumbs)

VitNode renders breadcrumb trails automatically in both the public site header and the AdminCP shell. **A route joins the trail by declaring a crumb**, and the trail reads parent to child:

```text
Home / Notes / Getting Started
```

A route declares only what its own crumb should display. VitNode manages the rest: accessible `<nav>` markup, separators, locale-aware links, and `aria-current="page"` semantics. No manual link construction, no duplicated trails, and zero drama.

## Static crumb [#static-crumb]

Declare a breadcrumb function directly inside `definePluginRoute`. Because it renders within the route's declared namespaces, `useTranslations` works out of the box:

```tsx title="plugins/site-notes/src/pages/notes-layout.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'

// [!code ++:7]
export const route = definePluginRoute({
  breadcrumb: () => {
    const t = useTranslations('@acme/site-notes.home')

return t('title')
  },
})

const NotesLayout = ({ children }: { children: React.ReactNode }) => {
  return (
    <div className="container mx-auto flex max-w-4xl flex-col gap-6 p-4">
      <header className="border-b pb-4">
        <h1 className="text-2xl font-bold tracking-tight text-balance">
          Notes
        </h1>
      </header>
      <main>{children}</main>
    </div>
  )
}

export default NotesLayout
```

{/* Image prompt: Modern web header showing breadcrumb trail Home / Notes with Notes highlighted in dark theme, 1440x900. */}

## Dynamic crumb from loader [#dynamic-crumb-from-loader]

When a route is dynamic (such as `/notes/:slug`), its breadcrumb can read directly from the route's `loaderData`. This ensures the trail shows human-readable titles instead of raw IDs, without firing a second network request:

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import {
  definePluginRoute,
  type PluginRoutePageProps,
} from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'

interface Note {
  content: string
  title: string
}

export const route = definePluginRoute({
  load: async ({ params }): Promise<Note> => {
    return {
      content: 'Loaded securely from your plugin loader.',
      title: `Note: ${params.slug}`,
    }
  },
  head: ({ loaderData, params }) => ({
    title: loaderData?.title ?? params.slug,
  }),
  // [!code ++:5]
  breadcrumb: ({ loaderData }) => {
    const t = useTranslations('@acme/site-notes.home')

return `${t('note')}: ${loaderData.title}`
  },
})

const NotePage = ({ loaderData }: PluginRoutePageProps<Note>) => {
  return (
    <article className="container mx-auto flex max-w-3xl flex-col gap-4 p-4">
      <h2 className="text-3xl font-semibold tracking-tight text-balance">
        {loaderData.title}
      </h2>
      <p className="text-muted-foreground leading-relaxed text-pretty">
        {loaderData.content}
      </p>
    </article>
  )
}

export default NotePage
```

The inline `breadcrumb` receives `{ loaderData, params, search }`—the exact same typed context passed to `head` and the page component.

{/* Image prompt: Header breadcrumb trail showing Home / Notes / Note: getting-started with the final crumb active, 1440x900. */}

## Omitting a route [#omitting-a-route]

Silence is the default: a route that declares no `breadcrumb` adds none, and the crumbs above it stay intact. Set `breadcrumb: false` when you want that silence to be deliberate—an `index()` page whose parent layout already names the screen, say:

```tsx title="plugins/site-notes/src/pages/notes-index-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

// [!code ++:3]
export const route = definePluginRoute({
  breadcrumb: false,
})

const NotesIndexPage = () => {
  return (
    <div>
      <p className="text-muted-foreground leading-relaxed text-pretty">
        Welcome to Site Notes.
      </p>
    </div>
  )
}

export default NotesIndexPage
```

Both spellings do the same thing. The trail simply ends at the deepest route that does declare a crumb, and that crumb is the one marked `aria-current="page"`.

## Trail behavior [#trail-behavior]

<Callout type="warn" title="Return text or inline elements, not a trail">
  A breadcrumb component should return text or an inline element (like an icon with text). Never render `<Breadcrumb>`, `<nav>`, links, or separators—the shell creates the landmark and manages links and separators for you.
</Callout>

<Callout type="info" title="AdminCP labels">
  In the AdminCP, breadcrumbs seamlessly coordinate with the admin navigation
  declared in `admin/nav.tsx`. When a route matches a sidebar item, its
  translated label is resolved automatically.
</Callout>

<Cards>
  <Card
    icon={<MapIcon />}
    title="Plugin Routes"
    description="Declare the route tree where layouts, pages, and dynamic segments define crumbs."
    href="/docs/dev/routing"
  />
  <Card
    icon={<DatabaseIcon />}
    title="Data Fetching"
    description="Fetch data in loaders so crumbs and pages receive typed loaderData."
    href="/docs/dev/fetcher"
  />
  <Card
    icon={<LayoutDashboardIcon />}
    title="AdminCP Pages"
    description="Mount plugin screens, navigation links, and permissions in the AdminCP."
    href="/docs/dev/plugins/admin"
  />
</Cards>

# Routing (/docs/dev/routing)

Start by [creating a plugin](/docs/dev/plugins/create). A plugin's `src/routes.ts`
is its promise to the app: which URLs it owns, and which module renders each one.
The host turns that promise into lazy TanStack Start routes—no copied page files,
no drama.

## Simple route [#simple-route]

You can declare a single page with a path and a lazy component:

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/notes', {
    component: lazy(() => import('./pages/note-page')),
    messages: ['@acme/site-notes.home'],
  }),
])
```

```tsx title="plugins/site-notes/src/pages/note-page.tsx"
import { useTranslations } from 'use-intl'

const NotePage = () => {
  const t = useTranslations('@acme/site-notes.home')

return (
    <div className="container mx-auto max-w-2xl p-4">
      <h1 className="text-2xl font-semibold tracking-tight text-balance">
        {t('title')}
      </h1>
    </div>
  )
}

export default NotePage
```

The `messages` array specifies which translation namespaces this page requires. A namespace must always be a **dotted path** into your plugin's message tree (such as `@acme/site-notes.home` rather than the bare plugin ID), allowing VitNode to only download the strings that this screen renders. For more details on message structure and limits, see the [Namespaces](/docs/dev/i18n/namespaces) and [Translating Pages](/docs/dev/i18n/pages) guides.

### Render without the main layout [#render-without-the-main-layout]

Every route picks a shell with `area`. The default is `'main'`, which frames the
page in the host's public layout—header, breadcrumbs, navigation, footer.

Set `area: 'blank'` for a page that should stand on its own: an embed, a kiosk
screen, a print view, a checkout step with nothing to wander off to.

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  // [!code ++:4]
  page('/notes/embed', {
    area: 'blank',
    component: lazy(() => import('./pages/notes-embed-page')),
  }),
])
```

A blank page is mounted at the root of the host's route tree, so it still gets
the document, the theme, the providers, and translations. It simply has no
chrome around it—which also means no breadcrumb trail, so give the page its own
way back.

Only a top-level route chooses an area. Every route nested in a `layout()`
renders in the shell its layout renders in, so it may not declare one of its
own.

## Dynamic route [#dynamic-route]

Use `:slug` for dynamic segments. VitNode converts it to TanStack Start's
internal `$slug` spelling while keeping your plugin portable.

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/notes/:slug', {
    component: lazy(() => import('./pages/note-page-slug')),
  }),
])
```

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'

const NotePage = ({ params }: PluginRoutePageProps) => {
  return (
    <article className="container mx-auto max-w-3xl p-4">
      <h2 className="text-3xl font-semibold tracking-tight text-balance">
        {params.slug}
      </h2>
    </article>
  )
}

export default NotePage
```

{/* Image prompt: Browser showing /notes/getting-started with a clean modern page heading 'getting-started' in dark theme, max-w-3xl container, 1440x900. */}

## Metadata (Head) [#metadata-head]

The `head` function returns the page's `<title>` and `<meta>` tags. It runs
after the loader, so it can use the data to make a unique title, description, and other SEO tags.

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import {
  // [!code ++:1]
  definePluginRoute,
  type PluginRoutePageProps,
} from '@vitnode/core/routing'

// [!code ++:6]
export const route = definePluginRoute({
  head: ({ params }) => ({
    description: 'A note delivered by the Site notes plugin.',
    title: params.slug,
  }),
})

export default NotePage
```

### Localizing metadata [#localizing-metadata]

`head` runs outside the React component tree—during SSR and on every
navigation—so hooks like `useTranslations` cannot reach it. Instead, `head`
receives `t`, a translator over the namespaces the route declared in `messages`:

```ts title="plugins/site-notes/src/routes.ts"
page('/notes/:slug', {
  component: lazy(() => import('./pages/note-page-slug')),
  // [!code ++:1]
  messages: ['@acme/site-notes.home'],
})
```

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  // [!code ++:4]
  head: ({ params, t }) => ({
    description: t('@acme/site-notes.home.desc'),
    title: `${t('@acme/site-notes.home.note')}: ${params.slug}`,
  }),
})
```

Keys are **full dotted paths**, namespace included. A component scopes itself
once with `useTranslations('@acme/site-notes.home')` and then asks for
`t('title')`; in `head` there is no component to scope, so the whole key is
spelled out.

Values interpolate the same way they do in a component:

```tsx
head: ({ t }) => ({
  title: t('@acme/site-notes.home.greeting', { name: 'Ada' }),
})
```

<Callout type="info" title="No extra request">
  The route's namespaces are already fetched before `head` runs—the loader warms
  them, and `head` runs after the loader—so translating metadata costs a cache
  read, not a round trip.
</Callout>

`load` receives the same `t`, for a title that depends on data you are already
fetching:

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
export const route = definePluginRoute({
  load: async ({ params, t }) => {
    const note = await findNote(params.slug)

return { heading: `${t('@acme/site-notes.home.note')}: ${note.title}` }
  },
  head: ({ loaderData }) => ({ title: loaderData?.heading }),
})
```

<Callout type="warn" title="Declare the namespace first">
  Calling `t` on a route that declares no `messages` throws, naming the
  namespace to add. Echoing the key back instead would ship
  `@acme/site-notes.home.title` into a `<title>`, where nothing would surface it
  until it showed up in a search result.
</Callout>

## Loaders [#loaders]

Fetch data in `load`. It runs on the server during SSR and on the client for subsequent navigations. Data returned from `load` is automatically passed to both `head` (for dynamic metadata) and the page component as `loaderData`.

<Callout type="info" title="Declare load above head">
  Always declare `load` **above** `head` in `definePluginRoute`. TypeScript
  infers the type of `loaderData` in `head` directly from the return type of
  `load`.
</Callout>

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import {
  definePluginRoute,
  type PluginRoutePageProps,
} from '@vitnode/core/routing'

interface Note {
  content: string
  title: string
}

export const route = definePluginRoute({
  // [!code ++:6]
  load: async ({ params }): Promise<Note> => {
    return {
      content: 'Loaded securely from your plugin loader.',
      title: `Note: ${params.slug}`,
    }
  },
  head: ({ loaderData, params }) => ({
    description: loaderData?.content,
    title: loaderData?.title ?? params.slug,
  }),
})

const NotePage = ({ loaderData }: PluginRoutePageProps<Note>) => {
  return (
    <article className="container mx-auto flex max-w-3xl flex-col gap-4 p-4">
      <h1 className="text-3xl font-semibold tracking-tight text-balance">
        {loaderData.title}
      </h1>
      <p className="text-muted-foreground leading-relaxed text-pretty">
        {loaderData.content}
      </p>
    </article>
  )
}

export default NotePage
```

{/* Image prompt: Browser preview showing the rendered note page with title and content in container, 1440x900. */}

## Breadcrumbs [#breadcrumbs]

Declare a crumb directly in `definePluginRoute` to contribute to the public header or AdminCP breadcrumb trail.

Because `breadcrumb` renders as a React component within the route's declared namespaces, `useTranslations` from `use-intl` works out of the box:

```tsx title="plugins/site-notes/src/pages/notes-layout.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'

// [!code ++:7]
export const route = definePluginRoute({
  breadcrumb: () => {
    const t = useTranslations('@acme/site-notes.home')

return t('title')
  },
})
```

For dynamic routes, the crumb receives `{ loaderData }` and can combine dynamic records with localized copy:

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { definePluginRoute } from '@vitnode/core/routing'
import { useTranslations } from 'use-intl'

export const route = definePluginRoute({
  load: async ({ params }): Promise<Note> => {
    return {
      content: 'Loaded securely from your plugin loader.',
      title: params.slug,
    }
  },
  head: ({ loaderData, params }) => ({
    title: loaderData?.title ?? params.slug,
  }),
  // [!code ++:5]
  breadcrumb: ({ loaderData }) => {
    const t = useTranslations('@acme/site-notes.home')

return `${t('note')}: ${loaderData.title}`
  },
})
```

For nested trails, deferred crumbs, and AdminCP trails, see the [Breadcrumbs guide](/docs/dev/routing/breadcrumbs).

## Loading states [#loading-states]

While a route's loader runs, VitNode displays its `pendingComponent`:

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'
// [!code ++:1]
import { TablePendingSkeleton } from '@vitnode/core/tanstack/pending'

export const routes = definePluginRoutes([
  page('/notes', {
    component: lazy(() => import('./pages/notes-page')),
    // [!code ++:1]
    pendingComponent: TablePendingSkeleton,
  }),
])
```

<Callout type="warn" title="A pending component is not code-split">
  A router draws it *before* the page's own chunk has arrived, so there is
  nothing to wait for it—TanStack Router never splits a `pendingComponent`, and
  neither does VitNode. It is imported outright into the initial bundle. Keep it
  to a skeleton.
</Callout>

VitNode ships pre-built skeleton shapes from `@vitnode/core/tanstack/pending`: `TablePendingSkeleton`, `FeedPendingSkeleton`, `FormPendingSkeleton`, `CardsPendingSkeleton`, `ProfilePendingSkeleton`, `AuthPendingSkeleton`, and `RoutePendingSpinner`.

To customize skeleton props (such as `rows` or `className`), rename the file to `routes.tsx` and return a JSX element:

```tsx title="plugins/site-notes/src/routes.tsx"
page('/notes', {
  component: lazy(() => import('./pages/notes-page')),
  // [!code ++:1]
  pendingComponent: () => <FeedPendingSkeleton rows={4} />,
})
```

If `pendingComponent` is omitted, the route falls back to the application's global `defaultPendingComponent`. Learn more in the [Loading States guide](/docs/dev/routing/loading).

## Missing pages [#missing-pages]

When a loader cannot find what the URL requested, throw `notFound()` from `@tanstack/react-router` to activate the route's `notFound` component:

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { notFound } from '@tanstack/react-router'
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async ({ params }) => {
    const note = await findNote(params.slug)

// [!code ++:3]
    if (!note) {
      throw notFound()
    }

return note
  },

// [!code ++:5]
  notFound: () => (
    <div className="container mx-auto p-4">
      <p className="text-muted-foreground leading-relaxed">No such note.</p>
    </div>
  ),
})
```

Unlike `pendingComponent`, `notFound` is part of the lazy page chunk and costs unvisited routes nothing. If omitted, the route falls through to the application's global `defaultNotFoundComponent`, preserving the application layout and navigation shell. Learn more in the [Errors & Not Found guide](/docs/dev/routing/not-found).

## Catch-all routes [#catch-all-routes]

A `*` segment matches every remaining segment of the URL, allowing a single route to own an entire subtree. It must be the final segment of a path and is only permitted on `page()` declarations (a layout ending in `*` would match before its child routes):

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  // [!code ++:3]
  page('/notes/*', {
    component: lazy(() => import('./pages/notes-catch-all')),
  }),
])
```

The page reads the matched trailing path from `params._splat`:

```tsx title="plugins/site-notes/src/pages/notes-catch-all.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'

const NotesCatchAll = ({ params }: PluginRoutePageProps) => {
  const segments = (params._splat ?? '').split('/').filter(Boolean)

return (
    <div className="container mx-auto max-w-3xl p-4">
      <p className="text-muted-foreground leading-relaxed">
        {segments.join(' / ')}
      </p>
    </div>
  )
}

export default NotesCatchAll
```

## Route protection (requires) [#route-protection-requires]

Protect pages or entire layouts by declaring `requires`. VitNode checks the visitor's authentication state before the route chunk downloads:

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  page('/notes/new', {
    component: lazy(() => import('./pages/new-note-page')),
    // [!code ++:1]
    requires: 'authenticated',
  }),
])
```

<Callout type="info" title="AdminCP routes are pre-guarded">
  Routes with `area: 'admin'` are automatically placed behind the AdminCP staff
  session guard and cannot declare `requires`. To restrict access to specific
  staff roles or permissions, gate content inside the route component or loader.
</Callout>

## Cache public pages [#cache-public-pages]

A page that looks the same for every visitor can declare `cache`, and VitNode reuses its server-rendered HTML for the given number of seconds:

```ts title="plugins/blog/src/routes.ts"
page('/blog/:slug', {
  cache: { maxAge: 300, staleWhileRevalidate: 60 }, // [!code ++]
  component: lazy(() => import('./pages/post-page')),
})
```

Routes are uncached by default, and a route with `requires` cannot be cached. [Cache server-rendered pages](/docs/dev/cache/pages) covers the setup and how the host app overrides a policy.

## Nested routes and layouts [#nested-routes-and-layouts]

A `layout()` wraps child routes in a shared UI frame without claiming a URL segment of its own. Use `index()` to render a page at the layout's root path.

Every path nested inside a layout is **relative** to its parent:

```ts title="plugins/site-notes/src/routes.ts"
import {
  definePluginRoutes,
  index,
  layout,
  lazy,
  page,
} from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  layout('/notes', {
    component: lazy(() => import('./pages/notes-layout')),
    messages: ['@acme/site-notes.home'],
    children: [
      index({
        component: lazy(() => import('./pages/notes-index-page')),
      }),
      page(':slug', {
        component: lazy(() => import('./pages/note-page-slug')),
      }),
    ],
  }),
])
```

A layout component renders `{children}`:

```tsx title="plugins/site-notes/src/pages/notes-layout.tsx"
import { useTranslations } from 'use-intl'

const NotesLayout = ({ children }: { children: React.ReactNode }) => {
  const t = useTranslations('@acme/site-notes.home')

return (
    <div className="container mx-auto flex max-w-4xl flex-col gap-6 p-4">
      <header className="border-b pb-4">
        <h1 className="text-2xl font-bold tracking-tight text-balance">
          {t('title')}
        </h1>
      </header>
      <main>{children}</main>
    </div>
  )
}

export default NotesLayout
```

## AdminCP routes [#admincp-routes]

Mount a screen in the staff-only Admin Control Panel by adding `area: 'admin'`. It automatically inherits the AdminCP shell, sidebar, and staff authentication guard:

```ts title="plugins/site-notes/src/routes.ts"
page('/admin/notes', {
  // [!code ++:1]
  area: 'admin',
  component: lazy(() => import('./pages/admin-notes-page')),
  messages: ['@acme/site-notes.admin'],
})
```

## Search parameters [#search-parameters]

Type and validate query strings (like pagination or filters). Declare `search` on the route for eager URL-level validation before code chunks load:

```ts title="plugins/site-notes/src/routes.ts"
page('/notes', {
  component: lazy(() => import('./pages/notes-page')),
  // [!code ++:3]
  search: (input: Record<string, unknown>) => ({
    page: Number(input.page) || 1,
  }),
})
```

The component receives typed `search` values and a `navigate` helper:

```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'

interface NotesSearch {
  page: number
}

const NotesPage = ({
  navigate,
  search,
}: PluginRoutePageProps<undefined, NotesSearch>) => (
  <div className="container mx-auto p-4">
    <button
      className="inline-flex items-center rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90"
      onClick={() => void navigate({ search: { page: search.page + 1 } })}
      type="button"
    >
      Next Page ({search.page})
    </button>
  </div>
)

export default NotesPage
```

<Cards>
  <Card
    icon={<DatabaseIcon />}
    title="Data Fetching"
    description="Learn universal fetchers, cache invalidation, and background mutations."
    href="/docs/dev/fetcher"
  />
  <Card
    icon={<MilestoneIcon />}
    title="Breadcrumbs"
    description="Customize static and dynamic breadcrumbs across public and admin pages."
    href="/docs/dev/routing/breadcrumbs"
  />
  <Card
    icon={<LoaderCircleIcon />}
    title="Loading States"
    description="Display debounced spinners and tailored skeleton fallbacks while pages stream."
    href="/docs/dev/routing/loading"
  />
  <Card
    icon={<TriangleAlertIcon />}
    title="Errors & Not Found"
    description="Render localized 404 and 500 boundaries while keeping application layouts intact."
    href="/docs/dev/routing/not-found"
  />
  <Card
    icon={<LanguagesIcon />}
    title="Translations"
    description="Stream localized message namespaces in parallel with route chunks using use-intl."
    href="/docs/dev/i18n/pages"
  />
  <Card
    icon={<LayoutDashboardIcon />}
    title="AdminCP Pages"
    description="Mount plugin screens, navigation links, and permissions in the AdminCP."
    href="/docs/dev/plugins/admin"
  />
</Cards>

# Loading States (/docs/dev/routing/loading)

While a route loader executes or a lazy page chunk downloads, VitNode provides instant visual feedback so users never see an unresponsive screen.

Loading states operate at two distinct layers:

1. **Global router transitions** — A non-intrusive spinner rendered when navigating between routes.
2. **Component-level Suspense** — Purpose-built skeleton shapes matching your layout while asynchronous data streams in.

## Global router pending state [#global-router-pending-state]

TanStack Router displays a pending component during route transitions. VitNode configures this globally in `router.tsx` using `RoutePendingSpinner` with built-in debouncing:

```tsx title="apps/web/src/router.tsx"
import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import { RoutePendingSpinner } from '@vitnode/core/tanstack/pending'

export function getRouter() {
  return createTanStackRouter({
    routeTree,
    // [!code ++:3]
    defaultPendingComponent: RoutePendingSpinner,
    defaultPendingMs: 150,
    defaultPendingMinMs: 300,
  })
}
```

- `defaultPendingMs: 150` — Prevents visual flickering on fast network responses by waiting 150ms before showing the spinner.
- `defaultPendingMinMs: 300` — Ensures that once shown, the spinner remains visible for at least 300ms to avoid jarring flashes.

{/* Image prompt: Minimal centered loading spinner in a clean dark UI shell with accessible aria-live indicator, 1440x900. */}

## Component skeletons with Suspense [#component-skeletons-with-suspense]

For feature pages with multiple asynchronous queries, wrap content in React `<Suspense>` using VitNode's pre-built pending skeletons:

```tsx title="plugins/site-notes/src/pages/notes-page.tsx"
import { FeedPendingSkeleton } from '@vitnode/core/tanstack/pending'
import { Suspense } from 'react'

const NotesList = () => {
  // Asynchronously fetched notes
  return <div>Notes List</div>
}

const NotesPage = () => {
  return (
    <div className="container mx-auto max-w-3xl p-4">
      {/* [!code ++:3] */}
      <Suspense fallback={<FeedPendingSkeleton rows={4} />}>
        <NotesList />
      </Suspense>
    </div>
  )
}

export default NotesPage
```

{/* Image prompt: Skeletons of note cards with pulsing placeholders for title, text lines, and avatar in dark theme, 1440x900. */}

## Pre-built skeleton shapes [#pre-built-skeleton-shapes]

Import pre-built skeletons directly from `@vitnode/core/tanstack/pending`:

## Customizing skeleton props [#customizing-skeleton-props]

All skeleton shapes accept props from `RoutePendingSkeletonProps` to adapt to your layout:

```tsx title="plugins/site-notes/src/pages/notes-admin-page.tsx"
import { TablePendingSkeleton } from '@vitnode/core/tanstack/pending'
import { Suspense } from 'react'

const AdminNotesPage = () => {
  return (
    <Suspense
      fallback={
        // [!code ++:4]
        <TablePendingSkeleton
          className="p-6"
          rows={8}
          withDescription={false}
        />
      }
    >
      <AdminNotesTable />
    </Suspense>
  )
}

export default AdminNotesPage
```

<Cards>
  <Card
    icon={<DatabaseIcon />}
    title="Data Fetching"
    description="Learn universal fetchers, cache invalidation, and background mutations."
    href="/docs/dev/fetcher"
  />
  <Card
    icon={<MapIcon />}
    title="Plugin Routes"
    description="Declare routes, lazy page components, metadata, and breadcrumbs."
    href="/docs/dev/routing"
  />
  <Card
    icon={<TriangleAlertIcon />}
    title="Errors & Not Found"
    description="Handle 404, 500, and error boundaries in routes."
    href="/docs/dev/routing/not-found"
  />
</Cards>

# Navigation (/docs/dev/routing/navigation)

Inside the app, use TanStack Router's `Link`. It builds the href, applies the
locale prefix, and preloads the destination on hover. You write the logical
path; the router writes the language.

## Example [#example]

```tsx
import { Link } from '@tanstack/react-router'

const DiscoverLink = () => <Link to="/discover">Discover</Link>
```

That renders `/discover` for an English reader and `/pl/discover` for a Polish
one - or `/pl/odkrywaj`, once the app [translates the path](/docs/dev/i18n/localized-urls).
Same component, same `to`, no branch and no `useLocale()` call.

## One route, two URLs [#one-route-two-urls]

`/discover` and `/pl/discover` are **one route**. The router's `rewrite` is what
makes that work, and it runs in both directions:

| Stage                                         | Value            | With `routePaths` |
| --------------------------------------------- | ---------------- | ----------------- |
| The address bar                               | `/pl/discover`   | `/pl/odkrywaj`    |
| What the route tree matches (`rewrite.input`) | `/discover`      | `/discover`       |
| What you write                                | `to="/discover"` | `to="/discover"`  |
| What React renders (`rewrite.output`)         | `/pl/discover`   | `/pl/odkrywaj`    |

A translated path is spelled by the same rewrite, so route files, route IDs and
every `to` stay English. With `i18n.domains`, the domain already says the
language, so on `vitnode.pl` the same link renders `/odkrywaj`.

`input` is why no route file anywhere in the app mentions a locale - there is no
`routes/pl/` directory and there is not going to be one. `output` reads the
locale off the router's own current location rather than off `window`, so the
href rendered during SSR is byte-identical to the one rendered after hydration.

So write the logical path. Two things that look reasonable and are not:

- **Building the prefix yourself.** ``to={`/${locale}/discover`}`` does not
  double up, because `localizeUrl` de-localizes before it prefixes and is
  therefore idempotent. What it does instead is discard the prefix you wrote and
  re-apply the reader's _current_ locale, so an English reader following your
  `/pl/discover` link lands on `/discover`. Not honoured; overwritten.
- **Naming a prefixed route.** `to="/pl/discover"` is not a path in the route
  tree, so the router's typed `to` refuses it.

<Callout type="info" title="`/admin` and `/api` carry no prefix at all">
  Both sit outside the localized URL space, so nothing is stripped from them and
  nothing is added. `/pl/admin/core` is therefore a mistake rather than a Polish
  page, and the app's request middleware 308-redirects it to `/admin/core` while
  storing `pl` in the language cookie - so the AdminCP still renders in the
  language the visitor just asked for. The same middleware canonicalises
  `/en/discover` to `/discover`, because the default locale is unprefixed and
  two indexable URLs for one page is one too many.
</Callout>

<Callout type="warn" title="An unknown prefix is a 404, not a fallback">
  Only a prefix the app would itself emit gets stripped, so `/xx/discover`
  reaches the route tree intact and matches nothing. That is deliberate: a
  silent fallback would serve the same page at infinitely many URLs.
</Callout>

## Update query state from a plugin page [#update-query-state-from-a-plugin-page]

Plugin route props expose a narrow `navigate` function for filters, sorting, and
pagination on the page already being viewed. It keeps the plugin independent of
the host router’s entire route tree.

```tsx title="plugins/catalog/src/pages/catalog-page.tsx"
import type { PluginRoutePageProps } from '@vitnode/core/routing'

interface CatalogSearch {
  page: number
}

const CatalogPage = ({
  navigate,
  search,
}: PluginRoutePageProps<undefined, CatalogSearch>) => (
  <button
    onClick={() =>
      void navigate({
        resetScroll: false,
        search: { page: search.page + 1 }, // [!code ++]
      })
    }
    type="button"
  >
    Next page
  </button>
)

export default CatalogPage
```

## Plugin route modules [#plugin-route-modules]

A plugin route should not import the host router. Use its `navigate` prop for
same-page filters, sort order, and pagination. For links to another internal
screen, let the host render a link component; a plain `<a>` is for another
origin only.

<Callout type="info" title="Keep plugins portable">
  `navigate` only changes this plugin page's query string. That small boundary
  is intentional—and saves future hosts from router spaghetti.
</Callout>

## Next [#next]

# Errors & Not Found (/docs/dev/routing/not-found)

In TanStack Start, error handling and missing routes are configured through route boundaries rather than static files. VitNode provides built-in, localized error layouts (`NotFound`, `Error500Page`, and `ErrorActions`) mounted directly inside your application shell—keeping navigation, headers, and themes intact when errors occur.

## 404 Not Found [#404-not-found]

### Throwing 404 in loaders [#throwing-404-in-loaders]

When a requested resource (such as a note slug or user ID) is not found in the database, throw `notFound()` from `@tanstack/react-router` inside `load`:

```tsx title="plugins/site-notes/src/pages/note-page-slug.tsx"
import { notFound } from '@tanstack/react-router'
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async ({ params }) => {
    const note = await fetchNote(params.slug)

// [!code ++:3]
    if (!note) {
      throw notFound()
    }

return note
  },
})
```

When thrown, TanStack Router catches the signal and halts page execution, rendering the nearest `notFoundComponent`.

### Unmatched URLs keep the main shell [#unmatched-urls-keep-the-main-shell]

When a visitor navigates to a non-existent URL, the main shell (`_main.tsx`) is
still matched, so the route is caught **inside** it.

This ensures visitors never hit a blank, unstyled screen: they retain the main site header, navigation bar, and theme switcher, while search crawlers receive a real HTTP `404` status code:

```tsx title="apps/web/src/router.tsx"
const routeTree = withVitNodeRoutes(
  fileRouteTree,
  pluginRouteSpecs(pluginRouteSources),
  {
    mountUnder: {
      admin: adminShellRoute,
      blank: fileRouteTree,
      main: mainShellRoute,
    },
  },
)
```

{/* Image prompt: VitNode 404 error page displayed inside the main site layout with header, 404 heading, localized description, and "Go back" / "Back to home" action buttons in dark theme, 1440x900. */}

## 500 Server & runtime errors [#500-server--runtime-errors]

When an unhandled exception or database failure occurs during SSR or client navigation, the router activates its `errorComponent`.

VitNode configures the global error boundary in `apps/web/src/router.tsx` using `Error500Page`:

```tsx title="apps/web/src/router.tsx"
import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import {
  Error500Page,
  ErrorActions,
  NotFound,
} from '@vitnode/core/tanstack/layout'

export function getRouter() {
  return createTanStackRouter({
    routeTree,
    // [!code ++:2]
    defaultNotFoundComponent: () => <NotFound actions={<ErrorActions />} />,
    defaultErrorComponent: () => <Error500Page actions={<ErrorActions />} />,
  })
}
```

`Error500Page` automatically renders localized strings from `core.global.errors.500`, keeping the error message friendly and clear while preserving layout structure.

{/* Image prompt: VitNode 500 internal server error page with large 500 status code, friendly error title, description, and recovery buttons in dark theme, 1440x900. */}

## Error action buttons [#error-action-buttons]

The `<ErrorActions />` component renders two primary recovery buttons:

1. **Go Back** (`router.history.back()`) — Takes the user to their previously viewed screen.
2. **Back to Home** (`/`) — Returns to the application homepage using locale-aware navigation.

You can also pass custom action elements into the `actions` prop of `NotFound` or `Error500Page`:

```tsx title="apps/web/src/routes/__root.tsx"
import { ErrorActions, NotFound } from '@vitnode/core/tanstack/layout'

export const Route = createRootRouteWithContext<RootRouterContext>()({
  // [!code ++:1]
  notFoundComponent: () => <NotFound actions={<ErrorActions />} />,
  component: RootComponent,
})
```

## Standard error codes [#standard-error-codes]

VitNode provides `ErrorContent` to render standardized error presentations across public and administrative pages:

<Callout type="info" title="Centralized error boundaries">
  Keep root error fallbacks in your host application (`apps/web`). Individual
  plugins should throw `notFound()` or errors from their loaders and let the
  centralized, localized layouts handle presentation.
</Callout>

<Cards>
  <Card
    icon={<LoaderCircleIcon />}
    title="Loading States"
    description="Render instant skeletons and spinners during route transitions."
    href="/docs/dev/routing/loading"
  />
  <Card
    icon={<MapIcon />}
    title="Plugin Routes"
    description="Declare URLs, lazy page components, metadata, and breadcrumbs."
    href="/docs/dev/routing"
  />
  <Card
    icon={<DatabaseIcon />}
    title="Data Fetching"
    description="Server and client data loading with universal fetchers."
    href="/docs/dev/fetcher"
  />
</Cards>

# Elasticsearch (/docs/dev/search-elasticsearch)

Use Elasticsearch when your site-wide search needs fuzzy matching, custom
ranking, or a search cluster separate from Postgres. VitNode keeps Postgres as
the canonical index; this adapter mirrors it, so switching is pleasantly boring.

### Install the adapter [#install-the-adapter]

Run this in the app or API workspace that owns `vitnode.api.config.ts`.

```bash tab="bun"
bun add @vitnode/elasticsearch@canary
```

```bash tab="pnpm"
pnpm add @vitnode/elasticsearch@canary
```

```bash tab="npm"
npm install @vitnode/elasticsearch@canary
```

</Tabs>

</Step>
<Step>

### Add the cluster URL and adapter [#add-the-cluster-url-and-adapter]

Set `ELASTICSEARCH_NODE` to your Elasticsearch or OpenSearch endpoint, then
register the adapter in the API config.

```bash title=".env"
ELASTICSEARCH_NODE=http://localhost:9200
```

```ts title="apps/api/src/vitnode.api.config.ts"
import { ElasticsearchSearchAdapter } from '@vitnode/elasticsearch' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:5]
  search: {
    adapter: ElasticsearchSearchAdapter({
      node: process.env.ELASTICSEARCH_NODE,
      index: 'vitnode',
    }),
  },
  plugins: [blogApiPlugin()],
})
```

For Elastic Cloud, use `cloudId` and `apiKey` instead of `node`. The adapter
also accepts `username` and `password` for a self-hosted secured cluster.

</Step>
<Step>

### Rebuild the mirror [#rebuild-the-mirror]

Restart the API, then open **Core → Advanced → Search** in the AdminCP and run
**Rebuild index**. New changes are mirrored automatically; the rebuild fills
the historical records already in Postgres. Rebuilding (and clearing a
collection) needs the **Rebuild and clear the search index** permission
(`system:can_manage_search`) - viewing the page alone is not enough.

{/* Image prompt: VitNode AdminCP search page showing Elasticsearch as connected, one “Rebuild index” button, a progress state, and collection counts. Dark theme, 1440x900. */}

</Step>
</Steps>

<Callout type="info" title="Upgrading an existing index">
  Documents now carry `authorIds` (a list) instead of `authorId`, plus drafts
  as private documents. If your index was created before that, delete it in
  Elasticsearch and run **Rebuild index**. VitNode recreates it with the new
  mapping.
</Callout>

<Callout type="info" title="Indexes created before uuid and bigint ids">
  Documents now carry an `itemKey` keyword with the record id as text, so
  [uuid and bigint](/docs/content-engine/id-strategy) records can be found.
  VitNode adds the field to an existing index the first time it uses it. Older
  documents get a value on the next **Rebuild index**; until then, results fall
  back to the numeric `itemId`, which works for serial ids only.
</Callout>

<Callout type="warn" title="Keep Postgres">
  Do not delete `core_search_index`. It remains VitNode's source of truth and
  lets you switch providers without losing your map back home.
</Callout>

## Next [#next]

# Search & Discovery (/docs/dev/search)

VitNode includes a unified site-wide search and discovery engine. Searchable records across all plugins are projected into the `core_search_index` table, powering `/search` and `/discover`.

<Callout type="info" title="Single table filtering">
  This guide covers **site-wide search**. For search boxes on individual tables,
  see [Search](/docs/dev/database/search).
</Callout>

## Quick start [#quick-start]

### Index when a record changes [#index-when-a-record-changes]

Index or update an item from any Hono route handler via `c.get("search")`:

```ts
// [!code ++:10]
await c.get('search').index({
  itemType: 'article',
  itemId: article.id,
  title: article.title,
  content: article.content, // HTML automatically stripped to plain text
  url: `/articles/${article.slug}`,
  authorIds: [article.authorId],
  isPublic: article.status === 'published',
  createdAt: article.createdAt,
})
```

</Step>
<Step>

### Delete removed records [#delete-removed-records]

When an item is deleted, remove it from the index:

```ts
await c.get('search').delete('article', article.id)
```

</Step>
<Step>

### Register a rebuild indexer [#register-a-rebuild-indexer]

To allow admins to re-index all historical content from the AdminCP, register a search indexer in your plugin's `config.api.ts`:

```ts title="plugins/blog/src/api/indexers/post.indexer.ts"
import { buildSearchIndexer } from '@vitnode/core/api/lib/search'
import { blog_posts } from '@/database/posts'

export const postSearchIndexer = buildSearchIndexer({
  itemType: 'article',
  totalCount: async (c) => {
    return await c.get('db').$count(blog_posts)
  },
  batch: async (c, { limit, offset }) => {
    const posts = await c
      .get('db')
      .select()
      .from(blog_posts)
      .limit(limit)
      .offset(offset)

return posts.map((post) => ({
      itemType: 'article',
      itemId: post.id,
      title: post.title,
      content: post.content,
      url: `/articles/${post.slug}`,
      authorIds: [post.authorId],
      createdAt: post.createdAt,
    }))
  },
})
```

```ts title="plugins/blog/src/config.api.ts"
export const blogApiPlugin = () =>
  buildApiPlugin({
    pluginId: 'blog',
    searchIndexers: [postSearchIndexer], // [!code ++]
  })
```

</Step>
</Steps>

## Pluggable Search Engines [#pluggable-search-engines]

VitNode supports two search engines:

1. **PostgreSQL Full-Text Search (Default)**:
   - Uses native `tsvector` + GIN indexes with weighted ranking (`title` weighted above `content`).
   - Zero additional infrastructure required.
2. **Elasticsearch (`@vitnode/elasticsearch`)**:
   - Offloads indexing and search to an Elasticsearch or OpenSearch cluster.
   - Unlocks fuzzy matching, phrase boosts, and decay scoring.

For setup, credentials, configuration, and the first rebuild, follow the
[Elasticsearch tutorial](/docs/dev/search-elasticsearch).

---

## Member timelines [#member-timelines]

Every member gets a timeline: everything credited to them, newest first. It lives on their profile (`/users/{nameCode}`) and on the **Timeline** tab of their AdminCP user page.

Who sees what depends on who's looking:

| Viewer | Published | Hidden | Drafts |
| --- | --- | --- | --- |
| Anyone, on `/search` and `/discover` | Yes | Only its authors and editors, with an eye-off icon | No |
| Anyone, on a member's profile | Yes | Only its authors and editors, with an eye-off icon | No |
| The member, on their own profile | Yes | Yes, with an eye-off icon | Yes, marked **Draft** |
| Staff, on the AdminCP user page | Yes | Yes, with an eye-off icon | Yes, marked **Draft** |

The **Hidden** column follows [Who can still see it](/docs/content-engine/content-visibility#who-can-still-see-it). An editor is staff with `can_edit` on the content type.

A draft has no public page yet, so its title isn't a link. Nobody gets sent to a 404.

Content Engine types opt in with `search.authorField`, which names the `field.user()` that holds the authors. With a multi-author field, every co-author gets the record on their timeline:

```ts title="plugins/blog/src/content/post.ts"
export const blogPostContentType = defineContentType({
  fields: {
    authorId: field.user({ min: 1, multiple: true, ordered: true }),
    // ...
  },
  search: {
    titleField: 'title',
    contentFields: ['title', 'content'],
    pathTemplate: '/blog/{slug}',
    authorField: 'authorId', // [!code ++]
  },
})
```

Every author is shown on the result, in the field's order, on `/search`, `/discover` and timelines alike. It shows overlapping avatars, then the names, such as **admin, devloop_tester and aXen**. Past three authors the list shortens to **admin, devloop_tester and 2 others**. Each hit in the API carries `authorIds` and `authors` (id, name, `nameCode`, avatar) in that order, and `author` stays the first one for code that only needs a single name. After turning `authorField` on for content that already exists, rebuild the index so older records get their authors.

The timelines come from two routes:

- `GET /api/@vitnode/core/search/timeline/{userId}` is public. It includes drafts only when the signed-in viewer is that member.
- `GET /api/@vitnode/core/admin/users/{id}/timeline` needs the `users` → `can_view` staff permission and returns every state.

---

## Result URLs for Content Engine types [#result-urls-for-content-engine-types]

`search.pathTemplate` is the English route of a result's page, with one `{slug}` placeholder. To turn search on for a content type, see [Content Engine search](/docs/content-engine/search). Leave the language out: VitNode adds the prefix, the domain and any translated segments from your app's [localized URL](/docs/dev/i18n/localized-urls) settings.

| `pathTemplate`           | English result          | Polish result (`as-needed`) | Polish result (with `domains`)       |
| :----------------------- | :---------------------- | :-------------------------- | :----------------------------------- |
| `/blog/{slug}`           | `/blog/hello-world`     | `/pl/blog/witaj-swiecie`    | `https://vitnode.pl/blog/witaj-swiecie` |

With `'/blog/:slug': '/wpisy/:slug'` in `routePaths.pl`, the Polish result becomes `/pl/wpisy/witaj-swiecie`.

Once `domains` is configured, every result URL is absolute, so a click always opens the right domain.

The rules:

- It starts with `/` and holds exactly one `{slug}`. No other placeholder, empty segment, `..` or whitespace.
- A page route has to serve it (`{slug}` read as `:slug`). If a plugin exports its content types from `src/content.ts` and none does, `dev` and `build` stop with `content-url-without-page`. See [Content URLs need a page](/docs/dev/i18n/localized-urls#content-urls-need-a-page).
- `{locale}` is no longer needed. A legacy leading `/{locale}/` (like `/{locale}/blog/{slug}`) is still accepted and stripped.
- `{locale}` anywhere else fails with: `search.pathTemplate "..." places "{locale}" somewhere other than the start of the path. The language is no longer part of the template: i18n.localePrefix, i18n.domains and i18n.routePaths now place it. Remove "{locale}" (recommended), or keep it only as the first segment ("/{locale}/...").`
- A content type that isn't localized can't use `{locale}` at all.

<Callout type="warn" title="Rebuild after changing URLs">
  Result URLs are stored when a record is indexed. After you change
  `pathTemplate`, `routePaths`, `domains` or `localePrefix`, rebuild the index
  below so older results stop pointing at the old addresses.
</Callout>

A document you index yourself with `c.get('search').index()` keeps its `url` exactly as you pass it, so pass the public URL for that document's language.

---

## AdminCP Search Management [#admincp-search-management]

{/* Image prompt: VitNode AdminCP Search settings screen at /admin/core/advanced/search. Dashboard displaying search index statistics, engine status (PostgreSQL / Elasticsearch), registered item types with indexed document counts, and a "Rebuild Index" button. Dark theme, 1440x900. */}

Manage search status at **Core → Advanced → Search** (`/admin/core/advanced/search`):

- View indexed record counts across all collections.
- Trigger background rebuilds of specific collections or the entire site.

A rebuild is a queued job, so it only runs once [cron](/docs/dev/cron) is running. Until then it waits in the queue, patient but unproductive.

---

## Search Document Reference [#search-document-reference]

## Learn More [#learn-more]

# Server Functions & Isomorphic Fetching (/docs/dev/server-functions)

VitNode keeps backend business logic in Hono API routes. The frontend's only job
is to call them - and for that, one universal fetcher covers SSR and browser
navigation at once.

## Decision Matrix [#decision-matrix]

| Goal                           | Recommended tool                                | Rationale                                                                                     |
| :----------------------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------------- |
| **Route data fetching**        | `fetcher` from `@vitnode/core/tanstack/fetcher` | One call site. SSR forwards the request; the browser calls `/api/*` directly.                 |
| **API endpoints & mutations**  | Hono API routes                                 | Enforces staff permissions, validation schemas, and database transactions.                    |
| **Cookie minting on the host** | `createServerFn` + the server fetcher           | Only code inside the host request can set response headers directly.                          |
| **Plugin server code**         | Hono API modules                                | **Plugins must never declare `createServerFn`** (uncompiled handlers resolve to `undefined`). |

<Callout type="warn" title="No createServerFn in plugins">
  A plugin package may declare `createIsomorphicFn`, but never `createServerFn`.
  Server functions belong exclusively to the host application.
</Callout>

---

## Fetching does not need `createIsomorphicFn` [#fetching-does-not-need-createisomorphicfn]

TanStack Router loaders run on the server for the first paint and in the browser
for every navigation after it. That used to mean writing both halves by hand:

```ts
// [!code --:3]
export const fetchDevices = createIsomorphicFn()
  .server(fetchDevicesOnServer)
  .client(fetchDevicesInBrowser)
```

The universal `fetcher` already is that boundary, so a feature writes the fetch
once - naming the plugin, and letting the route infer:

```ts title="plugins/devices/src/lib/fetch-devices.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'

// [!code ++:10]
export const fetchDevices = async () => {
  const response = await fetcher({
    plugin: '@vitnode/core',
    method: 'get',
    module: 'users',
    path: '/devices',
  })

return await response.json()
}
```

```tsx title="plugins/devices/src/pages/devices-page.tsx"
import { definePluginRoute } from '@vitnode/core/routing'

export const route = definePluginRoute({
  load: async () => await fetchDevices(), // [!code ++]
})
```

The initial render forwards the visitor's cookie, user-agent and IP through the
request-aware transport; later navigations are a direct same-origin `fetch` to
Hono. See [Fetcher](/docs/dev/fetcher) for the full contract.

`createIsomorphicFn` is still the right tool when the _two implementations
genuinely differ_ - reading a cookie from the request on the server and from
`document.cookie` in the browser, for instance. It is no longer how you fetch.

---

## When to use `createServerFn` (host app only) [#when-to-use-createserverfn-host-app-only]

Use `createServerFn` when your host application has to touch the response
itself - which in practice means cookies:

```ts title="apps/web/src/lib/auth.server.ts"
import { createServerFn } from '@tanstack/react-start'
import { fetcher } from '@vitnode/core/tanstack/fetcher/server'

export const signIn = createServerFn({ method: 'POST' })
  .validator((body: { email: string; password: string }) => body)
  .handler(async ({ data }) => {
    const response = await fetcher({
      plugin: '@vitnode/core',
      // [!code ++]
      allowSaveCookies: true,
      args: { body: data },
      method: 'post',
      module: 'users',
      path: '/sign_in',
    })

return { ok: response.ok }
  })
```

The call is the same shape as the universal one - `plugin`, `module`, `path`,
`method`, `args` - and it is typed from the same registry. What the server
fetcher adds is exactly what a browser cannot do:

Two things make this the exception rather than the rule:

- it needs `allowSaveCookies`, which only the **server** fetcher offers;
- it costs an extra hop - browser → server function → API. Reads should not pay
  it, which is exactly why they use the universal `fetcher` instead.

Keep code that imports `@vitnode/core/tanstack/fetcher/server` in a
`*.server.ts` file or inside a server function handler. The universal fetcher
rejects these three options at compile time, so a call that needs one cannot
end up in a shared module by accident.

## Learn More [#learn-more]

# Getting Started (/docs/dev/setup)

You need Node.js 22.18+ (or 24.11+, or 26+), Postgres (or Docker), and your
favorite package manager.
Choose a workspace with Turborepo if you will create plugins; plugins are the
home for product work, not an optional side quest.

### Scaffold the app [#scaffold-the-app]

```bash tab="bun"
bun create vitnode-app@canary
```

```bash tab="pnpm"
pnpm create vitnode-app@canary
```

```bash tab="npm"
npm create vitnode-app@canary
```

</Tabs>

Pick **Single App** for TanStack Start plus Hono at `/api`. Turn on
**Turborepo** if you intend to use `--plugin`; it gives the generator a
workspace root and a place for `plugins/*`.

</Step>
  <Step>

### Start the database [#start-the-database]

If you selected Docker, start Postgres and Redis locally:

```bash tab="bun"
bun run docker:dev
```

```bash tab="pnpm"
pnpm docker:dev
```

```bash tab="npm"
npm run docker:dev
```

</Tabs>

</Step>
 
  <Step>

### Start VitNode [#start-vitnode]

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

Open `http://localhost:3000`.

</Step>
</Steps>

## Keep going [#keep-going]

<Cards>
  <Card
    icon={<SettingsIcon />}
    title="Configuration"
    description="Locales, plugins, request middleware, and what a browser may hold."
    href="/docs/dev/configuration"
  />
  <Card
    icon={<PackagePlusIcon />}
    title="Create a plugin"
    description="Scaffold, register, and visit an installable feature package."
    href="/docs/dev/plugins/create"
  />
  <Card
    icon={<ServerIcon />}
    title="Deployments"
    description="Move your TanStack Start and Hono app to production."
    href="/docs/dev/deployments/self-hosted"
  />
  <Card
    icon={<BookOpenIcon />}
    title="First plugin tutorial"
    description="Follow a compact example that adds a real plugin page."
    href="/docs/guides/first-plugin"
  />
</Cards>

# Connected Accounts (/docs/dev/sso/connected-accounts)

**Settings → Connected accounts** (`/settings/sso`) is where a signed-in member manages their SSO accounts. It shows up in the settings menu as soon as at least one [SSO adapter](/docs/dev/sso) is configured - no extra setup, no extra redirect URIs.

// Image prompt: A settings page titled "Connected accounts" with three grouped lists - "Sign-in accounts" (Google with an email and "Connected Mar 14", Discord, Facebook with a Connect button), "Profile" (Avatar, First name, Last name rows, each with its current value and a "From Google" / "Manual" dropdown) and "Sync" (Google · First name, an "On sign-in" switch and a "Sync now" button), light theme, blue accents.

The page uses the same grouped rows as the rest of Settings, in three groups:

- **Sign-in accounts** - every configured provider with the connected account and date. **Connect**, **Import avatar and name** (a one-time copy after a preview, labelled with what the provider shares) and **Disconnect** live here.
- **Profile** - shown once a connected account can supply something. One row per field it can supply: the value the member has now, and a dropdown choosing where it comes from (**Manual**, or a connected account that can supply it). Changes save immediately.
- **Sync** - shown once a field follows an account. One row per account with the fields it covers, an **On sign-in** switch and **Sync now**, which confirms it's the member at the provider and updates those fields right away. They stay signed in; no sign-out, no new session.

Only the avatar, first name and last name are ever imported. Email, username, display name, language, birthday, phone and headline are never touched. A provider's email is shown as connection info and nothing more.

## How connecting works [#how-connecting-works]

1. The member selects **Connect**. `POST /users/sso/connections/{providerId}/authorize` stores a short-lived, single-use **state** bound to that member, that provider and the `link` intent - only its SHA-256 hash is kept, in `core_users_sso_operations`.
2. The browser goes to the provider and comes back to the usual callback, `/login/sso/{providerId}`. That page recognises a settings state and calls the authenticated `POST /users/sso/connections/{providerId}/callback` instead of the public sign-in.
3. The state is spent the moment it is looked up - even a failed attempt burns it - and it must still be fresh (ten minutes), for the same provider, the same intent and the **currently signed-in member**. Anything else is a `400 invalid_state`.
4. The provider account is linked to the member. Accounts are never merged by email.
5. The member lands back on `/settings/sso` with a toast.

A provider account already linked to someone else answers `409 account_taken`. A member can have **one account per provider**; a second one answers `409 provider_already_connected`. Both rules are unique constraints on `core_users_sso`, so two racing requests can't sneak past them.

Connecting never creates a session - public or AdminCP - and never changes the profile.

<Callout type="info">
  The public sign-in and the login-time "Connect *Provider* to your account"
  password flow work exactly as before. See [How Accounts Link](/docs/dev/sso#how-accounts-link).
</Callout>

## Disconnecting [#disconnecting]

`DELETE /users/sso/connections/{providerId}` removes the connection and its sync settings (the profile sources cascade). Values already imported stay on the profile.

It refuses with `409 last_sign_in_method` when nothing else could sign the member in. What counts:

| Method             | Counts when                                                        |
| ------------------ | ------------------------------------------------------------------ |
| Password           | password sign-in is enabled **and** the member has a password      |
| Passkeys           | passkeys are enabled **and** the member has at least one           |
| Other SSO accounts | the provider is still configured in `ssoAdapters`                  |

The check and the delete run in one transaction that locks the member's row - the same lock passkey removal takes - so two parallel requests can't remove the last two methods at once.

Disconnecting doesn't revoke anything at the provider. The page says so, and members remove the app in their provider account themselves.

## Import now [#import-now]

1. The member picks fields the adapter supports and selects **Continue**. The state now also carries the `import` intent and the chosen fields.
2. After the provider round trip, VitNode checks it's the **same provider account** that is connected (`409 account_mismatch` otherwise) and stores a ten-minute preview of just those fields.
3. `/settings/sso?import={providerId}` shows current values next to the new ones. The member confirms a subset, and `POST .../{providerId}/import` applies it. The preview works once.

A fresh round trip every time means no provider tokens are ever stored.

## Sync now [#sync-now]

Each field - `avatar`, `firstName`, `lastName` - has at most one source (`core_users_sso_profile_sources`, primary key `userId + field`). Different fields can use different providers. Picking a source in a field's dropdown moves the field to that account.

**Sync now** starts a round trip with the `sync` intent. The server - not the browser - decides which fields it covers: the ones sourced from that provider when the round trip starts (`400 nothing_to_sync` if there are none). On the way back it checks it's the same provider account (`409 account_mismatch`), re-reads the sources so a field made manual in the meantime is skipped, applies the values and answers with a per-field result. The member stays on `/settings/sso` with a toast, still signed in. No token is stored, and no session is created.

## Sync on sign-in [#sync-on-sign-in]

When the **On sign-in** switch is on, every sign-in through that provider refreshes the same fields automatically. It's optional - Sync now works without it. There's no polling and no background job.

The rules that keep this predictable:

- Connecting an account doesn't copy anything. Existing connections start as manual with sign-in updates off.
- A missing or empty value from the provider never erases a local one.
- Sync now and sign-in updates only ever touch fields sourced from that provider.
- Editing a field yourself - `PATCH /users/me`, an avatar upload or removal, or staff changing the avatar in the AdminCP - switches that field back to manual.
- Importing a field that syncs from a different provider switches it to manual too, and the response lists it in `manualFields`.
- Role limits still apply: personal information rules for names, avatar upload permission and size for the avatar. Importing names never turns on `showRealName`.
- Anything that goes wrong during a sign-in sync is swallowed - the member is still signed in.

## Avatars [#avatars]

Imported avatars go through the normal avatar pipeline (`setUserImage`), so storage, image processing, file ownership and cleanup of the previous avatar are the same as an upload. The download (`downloadRemoteImage`) only speaks HTTPS, resolves the host and refuses private, loopback, link-local and reserved addresses - again at connect time, and again after every redirect (three at most) - caps the size at the role's limit (5 MB hard cap), and trusts the bytes, not the `Content-Type`: only real JPEG, PNG or WebP files under 8192 × 8192 pass.

The URL and a SHA-256 of the last imported picture are kept on the connection, so the same avatar isn't downloaded again while it's still shown, or stored twice when a provider hands out a new URL for the same image. A failed download leaves the current avatar alone.

## API [#api]

All routes live under `users/sso/connections`, need a signed-in member, and use the public session only.

| Method   | Path                      | Does                                      |
| -------- | ------------------------- | ----------------------------------------- |
| `GET`    | `/`                       | Providers, connections, sources, sign-in summary |
| `PUT`    | `/preferences`            | Field sources and sync toggles            |
| `POST`   | `/{providerId}/authorize` | Starts a `link`, `import` or `sync` round trip |
| `POST`   | `/{providerId}/callback`  | Finishes it (`sync` answers with `results`) |
| `GET`    | `/{providerId}/import`    | The pending import preview                |
| `POST`   | `/{providerId}/import`    | Applies selected preview fields           |
| `DELETE` | `/{providerId}/import`    | Discards the preview                      |
| `DELETE` | `/{providerId}`           | Disconnects                               |

```ts title="Calling it from your own UI"
import { fetcher } from "@vitnode/core/tanstack/fetcher"

const res = await fetcher({
  plugin: "@vitnode/core",
  method: "get",
  module: "users/sso/connections",
  path: "/",
})
```

Mutations take JSON bodies, which the browser can't send cross-site without a CORS preflight, on top of the API's CSRF middleware. Provider tokens never leave the server and never reach logs or events.

## Events [#events]

- [`user.sso.linked`](/docs/dev/events/built-in-events) - a provider was connected.
- [`user.sso.unlinked`](/docs/dev/events/built-in-events) - a provider was disconnected.
- [`user.sso.profile_synced`](/docs/dev/events/built-in-events) - profile fields changed because of a provider.

## Adapter support [#adapter-support]

Which fields a provider can supply comes from the adapter's `profileFields`. The page tells "this provider can't provide it" apart from "this provider didn't send it this time".

| Adapter  | Avatar | First name | Last name |
| -------- | ------ | ---------- | --------- |
| Google   | ✓      | ✓          | ✓         |
| Discord  | ✓      | -          | -         |
| Facebook | ✓      | ✓          | ✓         |

Discord has no real-name fields, and VitNode never guesses a first and last name from a username or a full name. For your own provider, see [Custom SSO Adapter](/docs/dev/sso/custom-adapter#profile-data).

# Custom SSO Adapter (/docs/dev/sso/custom-adapter)

VitNode includes built-in SSO adapters for Google, Discord, and Facebook. You can connect any other OAuth2 provider (e.g. GitHub, Apple, Slack) by implementing the `SSOApiPlugin` interface. State cookie generation, user session linking, and login buttons are handled automatically.

## Quick start: GitHub SSO Adapter [#quick-start-github-sso-adapter]

Implement the 5 interface methods and register the adapter in `vitnode.api.config.ts`:

### 1. Build the Adapter [#1-build-the-adapter]

```ts title="apps/api/src/utils/sso/github.ts"
import type { SSOApiPlugin } from "@vitnode/core/api/models/sso"
import { getRedirectUri } from "@vitnode/core/api/models/sso"

export const GitHubSSOApiPlugin = ({
  clientId,
  clientSecret,
}: {
  clientId: string
  clientSecret: string
}): SSOApiPlugin => {
  const id = "github"
  const redirectUri = getRedirectUri(id)

return {
    id,
    name: "GitHub",
    profileFields: ["avatar"],
    // 1. Build Authorization URL
    getUrl: ({ state }) =>
      `https://github.com/login/oauth/authorize?client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}&scope=read:user,user:email&state=${state}`,

// 2. Exchange Authorization Code for Token
    fetchToken: async (code) => {
      const response = await fetch("https://github.com/login/oauth/access_token", {
        method: "POST",
        headers: {
          Accept: "application/json",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          client_id: clientId,
          client_secret: clientSecret,
          code,
          redirect_uri: redirectUri,
        }),
      })

return await response.json()
    },

// 3. Retrieve User Profile & Email
    fetchUser: async ({ access_token, token_type }) => {
      const headers = { Authorization: `${token_type} ${access_token}` }

// Fetch Profile
      const userRes = await fetch("https://api.github.com/user", { headers })
      const user = await userRes.json()

// Fetch Primary Email
      const emailRes = await fetch("https://api.github.com/user/emails", { headers })
      const emails: Array<{ email: string; primary: boolean; verified: boolean }> =
        await emailRes.json()
      const primaryEmail = emails.find((e) => e.primary && e.verified)?.email
      if (!primaryEmail) throw new Error("GitHub account has no verified email")

return {
        id: String(user.id),
        email: primaryEmail,
        username: user.login,
        avatarUrl: user.avatar_url,
      }
    },
  }
}
```

---

### 2. Register in API Configuration [#2-register-in-api-configuration]

```ts title="apps/api/src/vitnode.api.config.ts"
import { buildApiConfig } from "@vitnode/core/vitnode.config"
import { GitHubSSOApiPlugin } from "./utils/sso/github"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      GitHubSSOApiPlugin({
        clientId: process.env.GITHUB_CLIENT_ID!,
        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      }),
    ],
  },
})
```

A **GitHub** login button automatically renders on `/login` and `/register`, and `/login/sso/github` routes incoming authentication requests. It is a neutral, text-only button until you give the adapter an [icon and a brand color](/docs/dev/sso/icons).

---

## `SSOApiPlugin` Interface Reference [#ssoapiplugin-interface-reference]

<TypeTable
  type={{
    id: {
      description: "Unique slug for the provider (e.g. 'github', 'slack'). Used in callback URLs.",
      required: true,
      type: "string",
    },
    name: {
      description: "Display name shown on the login button.",
      required: true,
      type: "string",
    },
    icon: {
      description: "Brand mark for the login button: inline SVG markup or an image URL. See Provider Icons and Colors.",
      required: false,
      type: "string",
    },
    brandColor: {
      description: "Hex color (#RGB or #RRGGBB) that fills the login button. The label turns white or near-black, whichever reads better. See Provider Icons and Colors.",
      required: false,
      type: "string",
    },
    getUrl: {
      description: "Returns the provider authorization redirect URL.",
      required: true,
      type: "({ state: string }) => string",
    },
    fetchToken: {
      description: "Exchanges code for access_token.",
      required: true,
      type: "(code: string) => Promise<{ access_token: string; token_type: string }>",
    },
    fetchUser: {
      description: "Fetches the user profile: id, email, username, and optionally avatarUrl, firstName and lastName. Return only an email the provider has verified - VitNode treats it as confirmed and will mark a matching unconfirmed account verified. The built-in adapters reject unverified addresses with a 400.",
      required: true,
      type: "(token: TokenResponse) => Promise<SSOProviderUser>",
    },
    profileFields: {
      description: "Which profile fields the provider can supply for Connected accounts: 'avatar', 'firstName', 'lastName'. Leave it out and nothing is ever imported from this adapter.",
      required: false,
      type: "readonly ('avatar' | 'firstName' | 'lastName')[]",
    },
  }}
/>

See [Provider Icons and Colors](/docs/dev/sso/icons) for the accepted `icon` and `brandColor` formats, and for registering a React component instead.

## Profile data [#profile-data]

[Connected accounts](/docs/dev/sso/connected-accounts) can import a member's avatar, first name and last name from your provider. Two steps:

1. Declare what the provider can supply in `profileFields`.
2. Return those values from `fetchUser` as `avatarUrl`, `firstName` and `lastName`.

```ts
fetchUser: async ({ access_token, token_type }) => {
  // ...
  return {
    id: String(user.id),
    email: primaryEmail,
    username: user.login,
    avatarUrl: user.avatar_url ?? null,
  }
},
profileFields: ["avatar"],
```

All three are optional, so adapters written before this still work - they just have nothing to import. A few rules keep imports honest:

- Return `null` (or leave it out) when the provider has no value. VitNode never erases a member's value with an empty one.
- Only send separate first and last names the provider actually has. Don't split a full name - `"Mary Ann Smith"` has no safe answer.
- `avatarUrl` must be `https`. VitNode downloads and re-stores it itself, with SSRF protection and size and type checks, so you don't have to.
- Don't add scopes just for profile data. If a field needs extra permission, leave it out of `profileFields`.

## Built-in SSO Adapters [#built-in-sso-adapters]

# Discord (/docs/dev/sso/discord)

Discord is the quickest of the three to set up: no consent screen review, no app
modes, no verification. Create an application, add one redirect URL, copy two
values.

## Quick start [#quick-start]

If you already have a client ID and secret, this is the entire integration.

```bash title=".env"
DISCORD_CLIENT_ID=1234567890123456789
DISCORD_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```ts title="src/vitnode.api.config.ts"
import { DiscordSSOApiPlugin } from '@vitnode/core/api/adapters/sso/discord' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      DiscordSSOApiPlugin({
        clientId: process.env.DISCORD_CLIENT_ID,
        clientSecret: process.env.DISCORD_CLIENT_SECRET,
      }),
    ],
  },
})
```

Restart the API and a **Discord** button appears on `/login`.

## Set up the application [#set-up-the-application]

### Sign in to the Discord Developer Portal [#sign-in-to-the-discord-developer-portal]

Go to the [Discord Developer Portal](https://discord.com/developers/applications)
and sign in with the Discord account that should own the application.

</Step>

<Step>

### Create a new application [#create-a-new-application]

Press **New Application**, give it the name visitors will see on the
authorization screen, and accept the terms.

{/* Image prompt: The Discord Developer Portal applications list with the "New Application" dialog open and a name typed into the field, dark theme, 1100x600. */}

</Step>

<Step>

### Add the redirect URL [#add-the-redirect-url]

Open **OAuth2** in the left navigation and, under **Redirects**, press **Add
Redirect**. Paste the URI for the origin you are running and save.

VitNode builds this URI from `VITNODE_WEB_URL`, so it has to match exactly -
no trailing slash, no locale prefix.

| Environment                           | Redirect URL                                |
| ------------------------------------- | ------------------------------------------- |
| Development (`VITNODE_WEB_URL` unset) | `http://localhost:3000/login/sso/discord`   |
| Production                            | `https://your-domain.com/login/sso/discord` |

Add both entries so one application covers local development and your live site.

{/* Image prompt: The Discord Developer Portal OAuth2 page with the "Redirects" section showing one entry reading http://localhost:3000/login/sso/discord and the "Save Changes" bar at the bottom, dark theme, 1100x500. */}

<Callout type="warn" title="Invalid OAuth2 redirect_uri">
  Discord rejects the authorization request outright if the URL is not in this
  list, before the visitor sees anything. If pressing the button lands you on a
  Discord error page rather than an authorization prompt, this is why.
</Callout>

</Step>

<Step>

### Copy the client ID and secret [#copy-the-client-id-and-secret]

Still on the **OAuth2** page, the **Client ID** and **Client Secret** are in the
client information block at the top. Press **Reset Secret** if the secret was
never revealed or you have lost it - Discord shows it once.

{/* Image prompt: The Discord Developer Portal OAuth2 page client information block showing "Client ID" with a Copy button and "Client Secret" with a Reset Secret button, values redacted, dark theme, 1100x450. */}

</Step>

<Step>

### Set the environment variables [#set-the-environment-variables]

Server-side variables, so leave them out of `clientEnv` - that list is what
publishes a value to the browser bundle, and a client secret in the browser
bundle is a client secret you have published.

```bash title=".env"
DISCORD_CLIENT_ID=1234567890123456789 # [!code ++]
DISCORD_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # [!code ++]
```

</Step>

<Step>

### Register the adapter [#register-the-adapter]

Add `DiscordSSOApiPlugin` to `authorization.ssoAdapters`. It is a plain factory
function, not a class - there is no `new`.

```ts title="src/vitnode.api.config.ts"
import { DiscordSSOApiPlugin } from '@vitnode/core/api/adapters/sso/discord' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

The redirect URI is computed when this file is evaluated, so restart the API
rather than relying on a hot reload:

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

</Step>

<Step>

### Verify it works [#verify-it-works]

Ask the API what it thinks it supports:

```bash
curl http://localhost:3000/api/@vitnode/core/middleware
# {"isEmail":false,"sso":[{"id":"discord","name":"Discord"}]}
```

Then open `/login` and press **Discord**. You should see Discord's "connect to"
authorization prompt listing your username and email, get bounced back to
`/login/sso/discord?code=...&state=...`, and land on the front page signed in.

{/* Image prompt: The VitNode /login page with the email and password fields below a blurple button labelled "Continue with Discord" and a divider reading "Or continue with email", dark theme, 900x850. */}

</Step>

</Steps>

## What the adapter asks Discord for [#what-the-adapter-asks-discord-for]

Useful when you are debugging an authorization prompt that lists the wrong
permissions.

| Setting       | Value                                  |
| ------------- | -------------------------------------- |
| Authorize URL | `https://discord.com/oauth2/authorize` |
| Token URL     | `https://discord.com/api/oauth2/token` |
| Profile URL   | `https://discord.com/api/users/@me`    |
| Scopes        | `identify email`                       |
| Provider id   | `discord`                              |
| Fields read   | `id`, `email`, `username`, `avatar`    |

Both scopes are required: `identify` for the id and username, `email` for the
address the account is created with.

The `avatar` hash becomes
`https://cdn.discordapp.com/avatars/{id}/{avatar}.png?size=512`, which
[Connected accounts](/docs/dev/sso/connected-accounts) can import. A member
still on Discord's default avatar has none. Discord has no first or last name,
and VitNode doesn't guess one from `username` or `global_name`, so only the
avatar is offered.

## Gotchas [#gotchas]

<Callout type="warn" title="An account with no email cannot sign in">
  The adapter requires `email` in Discord's profile response and answers `400`
  when it is absent - which is what happens if the `email` scope is dropped, or
  if the Discord account genuinely has no address on it. The visitor sees the
  generic error screen.
</Callout>

<Callout type="warn" title="Discord's email verification flag is not checked">
  Unlike the Google adapter, which rejects an unverified address, this one takes
  Discord's `email` at face value and never reads Discord's `verified` field. If
  you need that guarantee, copy the adapter into your own project and add the
  check - see [Custom adapter](/docs/dev/sso/custom-adapter).
</Callout>

<Callout type="warn" title="A missing key fails on click, not on boot">
  A `DiscordSSOApiPlugin` whose `clientId` is `undefined` registers happily -
  the button renders and the provider is listed - and throws `Missing Discord
  client ID` the moment somebody presses it. A button that only raises an error
  toast is an environment problem, not a portal problem.
</Callout>

## Next [#next]

# Facebook (/docs/dev/sso/facebook)

Facebook sign-in goes through a Meta app with the **Facebook Login** use case
switched on. Meta calls the two credentials an **App ID** and an **App Secret**;
VitNode calls them `clientId` and `clientSecret`, and they are the same two
strings.

## Quick start [#quick-start]

If you already have an App ID and App Secret, this is the entire integration.

```bash title=".env"
FACEBOOK_CLIENT_ID=1234567890123456
FACEBOOK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

```ts title="src/vitnode.api.config.ts"
import { FacebookSSOApiPlugin } from '@vitnode/core/api/adapters/sso/facebook' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      FacebookSSOApiPlugin({
        clientId: process.env.FACEBOOK_CLIENT_ID,
        clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
      }),
    ],
  },
})
```

Restart the API and a **Facebook** button appears on `/login`. The rest of this
page is how to get those two values.

## Set up the Meta app [#set-up-the-meta-app]

### Sign in to Meta for Developers [#sign-in-to-meta-for-developers]

Go to [developers.facebook.com](https://developers.facebook.com/) and sign in
with the Facebook account that should own the app. Meta walks you through
registering as a developer the first time, which means confirming your contact
details before you can create anything.

</Step>

<Step>

### Create an app [#create-an-app]

From **My Apps**, press **Create App**. The first screen wants an **App name** -
this is what visitors read on the login dialog - and an **App contact email**.

</Step>

<Step>

### Choose the Facebook Login use case [#choose-the-facebook-login-use-case]

On the **Use cases** step, tick **Authenticate and request data from users with
Facebook Login**. This is the one that gives the app an OAuth dialog; the others
(Ads Manager, Threads, games) do not, and Meta will not let you combine some of
them on one app.

Finish the wizard - the **Business** step lets you skip connecting a business
portfolio, and **Finalize** creates the app.

</Step>

<Step>

### Add the OAuth redirect URI [#add-the-oauth-redirect-uri]

In the app dashboard, open the Facebook Login use case's settings - **Use cases →
Authenticate and request data from users with Facebook Login → Customize →
Settings** on a new app, or **Products → Facebook Login → Settings** on an older
one. Paste your URI into **Valid OAuth Redirect URIs** and save.

VitNode builds this URI itself, from `VITNODE_WEB_URL`, so it has to match
character for character - no trailing slash, no locale prefix.

| Environment                           | Valid OAuth Redirect URI                     |
| ------------------------------------- | -------------------------------------------- |
| Development (`VITNODE_WEB_URL` unset) | `http://localhost:3000/login/sso/facebook`   |
| Production                            | `https://your-domain.com/login/sso/facebook` |

{/* Image prompt: The Meta app dashboard Facebook Login Settings panel with "Valid OAuth Redirect URIs" holding one entry reading https://your-domain.com/login/sso/facebook, the "Client OAuth login" and "Web OAuth login" toggles visible above it, light theme, 1200x700. */}

<Callout type="warn" title="Meta wants HTTPS in production">
  **Valid OAuth Redirect URIs** rejects a plain `http://` URL for a public
  domain, so a production entry has to be `https://`. `http://localhost` is the
  exception Meta makes for development, which is why the table above has two
  rows rather than one.
</Callout>

</Step>

<Step>

### Copy the App ID and App Secret [#copy-the-app-id-and-app-secret]

Go to **App settings → Basic** in the left navigation. The **App ID** is in plain
text; the **App Secret** is behind a **Show** button and your password.

</Step>

<Step>

### Set the environment variables [#set-the-environment-variables]

Server-side variables, so leave them out of `clientEnv` - that list is what
publishes a value to the browser bundle, and an app secret in the browser bundle
is an app secret you have published.

```bash title=".env"
FACEBOOK_CLIENT_ID=1234567890123456 # [!code ++]
FACEBOOK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # [!code ++]
```

</Step>

<Step>

### Register the adapter [#register-the-adapter]

Add `FacebookSSOApiPlugin` to `authorization.ssoAdapters` in your API config. It
is a plain factory function, not a class - there is no `new`.

```ts title="src/vitnode.api.config.ts"
import { FacebookSSOApiPlugin } from '@vitnode/core/api/adapters/sso/facebook' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

The redirect URI is computed when this file is evaluated, so restart the API
rather than relying on a hot reload:

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

</Step>

<Step>

### Verify it works [#verify-it-works]

Ask the API what it thinks it supports:

```bash
curl http://localhost:3000/api/@vitnode/core/middleware
# {"isEmail":false,"sso":[{"id":"facebook","name":"Facebook"}]}
```

Then open `/login` and press **Facebook**. You should get Meta's "Continue as
..." dialog, be bounced back to `/login/sso/facebook?code=...&state=...`, and
land on the front page signed in. Your account now has a row in `core_users_sso`
with `providerId` `facebook`.

{/* Image prompt: The VitNode /login page with the password form above a divider reading "Or continue With" and two outline buttons labelled Google and Facebook side by side, dark theme, 900x800. */}

</Step>

<Step>

### Publish the app [#publish-the-app]

While the app is **Unpublished** (the badge next to **Publish** in the
screenshot above), only people with a role on it - admins, developers, testers -
can sign in. Everyone else is turned away at Meta's dialog before VitNode ever
sees a callback. Go to **Publish** and switch the app live once the round trip
works.

`public_profile` and `email` are both standard-access permissions, so this does
not require App Review. Ask for anything beyond them and it will.

{/* Image prompt: The Meta app dashboard Publish page showing the app status as Unpublished with the requirements checklist and the go-live button, light theme, 1100x600. */}

</Step>

</Steps>

## What the adapter asks Facebook for [#what-the-adapter-asks-facebook-for]

Useful when you are debugging a login dialog that shows more or fewer
permissions than you expected.

| Setting       | Value                                                      |
| ------------- | ---------------------------------------------------------- |
| Authorize URL | `https://www.facebook.com/v26.0/dialog/oauth`              |
| Token URL     | `https://graph.facebook.com/v26.0/oauth/access_token`      |
| Profile URL   | `https://graph.facebook.com/v26.0/me`                      |
| Scopes        | `public_profile,email`                                     |
| Provider id   | `facebook`                                                 |
| Fields read   | `id`, `name`, `email`, `first_name`, `last_name`, `picture.width(512).height(512){url,is_silhouette}` |

The account name VitNode creates comes from Facebook's `name` field, stripped of
characters that cannot appear in a profile URL. The Graph API version is pinned
to `v26.0` in the adapter (`FACEBOOK_GRAPH_VERSION`), so a Meta version bump
never changes what this install sends.

`first_name`, `last_name` and `picture` are default public profile fields, so
[Connected accounts](/docs/dev/sso/connected-accounts) can import them without
asking for anything beyond `public_profile`. The default silhouette picture
counts as no avatar.

## Gotchas [#gotchas]

<Callout type="warn" title="An account with no email cannot sign in">
  The adapter requires `email` in the Graph response and answers `400` when it
  is missing - which happens if the visitor unticks the email permission on the
  login dialog, or if the account was created with a phone number and has no
  address at all. The visitor sees the generic error screen, not an explanation.
</Callout>

<Callout type="warn" title="Facebook's own email verification is not checked">
  Unlike the [Google adapter](/docs/dev/sso/google), which rejects an unverified
  address, this one takes the Graph API's `email` at face value. If you need a
  stronger guarantee, copy the adapter into your own project and add the check -
  see [Custom adapter](/docs/dev/sso/custom-adapter).
</Callout>

<Callout type="warn" title="A missing key fails on click, not on boot">
  A `FacebookSSOApiPlugin` whose `clientId` is `undefined` registers happily -
  the button renders and the provider is listed - and throws `Missing Facebook
  client ID` the moment somebody presses it. A button that only raises an error
  toast is an environment problem, not a dashboard problem.
</Callout>

<Callout
  type="warn"
  title="An email that already has a password account is a dead end"
>
  If someone registered with the same address using the password form, the
  callback answers `409` and offers them the login page instead. There is no
  link-an-existing-account screen yet - see [how the callback handles
  accounts](/docs/dev/sso#what-the-callback-does-with-the-account).
</Callout>

## Next [#next]

# Google (/docs/dev/sso/google)

Google is the provider most people want first. The whole job is: create an OAuth
client in the Google Auth Platform, give it the redirect URI VitNode already
decided on, and pass the two credentials to `GoogleSSOApiPlugin`.

## Quick start [#quick-start]

If you already have a client ID and secret, this is the entire integration.

```bash title=".env"
GOOGLE_CLIENT_ID=1234567890-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx
```

```ts title="src/vitnode.api.config.ts"
import { GoogleSSOApiPlugin } from '@vitnode/core/api/adapters/sso/google' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  plugins: [],
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      GoogleSSOApiPlugin({
        clientId: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
      }),
    ],
  },
})
```

Restart the API and a **Google** button appears on `/login`. The rest of this
page is how to get those two values.

## Set up the OAuth client [#set-up-the-oauth-client]

### Sign in to Google Cloud [#sign-in-to-google-cloud]

Go to the [Google Cloud Console](https://console.cloud.google.com/) and sign in
with the account that should own the OAuth client. It does not have to be the
account you sign in to your own site with.

</Step>

<Step>

### Pick or create a project [#pick-or-create-a-project]

An OAuth client belongs to a project, so select one from the project picker in
the top bar - or create one if this is a fresh account. Name it after your site;
the name is internal and never shown to visitors.

{/* Image prompt: The Google Cloud Console project picker dialog open, showing the "Select a project" list with a "New project" button in the top right, light theme, 1200x700. */}

</Step>

<Step>

### Open the Google Auth Platform [#open-the-google-auth-platform]

Type `Google Auth Platform` into the console's search bar and open the first
result. This is the section that used to be called "OAuth consent screen", and
it is where both the consent details and the clients live.

{/* Image prompt: The Google Cloud Console top search bar with "Google Auth Platform" typed in and the matching product result highlighted in the dropdown, light theme, 1200x400. */}

</Step>

<Step>

### Fill in the consent details [#fill-in-the-consent-details]

Google will not issue a client until it knows what to show on the consent
screen. Provide the **App name** - this is the name visitors read in "Sign in to
continue to ..." - and a **Support email**.

Then, under **Audience**, choose **External** so anyone with a Google account can
sign in. **Internal** restricts sign-in to a single Google Workspace
organisation, which is almost never what a public site wants.

{/* Image prompt: The Google Auth Platform "Audience" step with the "External" radio option selected and the "Internal" option visible above it, light theme, 1000x600. */}

</Step>

<Step>

### Create the client and set the redirect URI [#create-the-client-and-set-the-redirect-uri]

Go to **Clients** in the left navigation and press **Create client**.

1. Application type: **Web application**.
2. Name: anything - this one is internal too.
3. Under **Authorized redirect URIs**, add the URI for every origin you run.

VitNode builds this URI itself, from `VITNODE_WEB_URL`, so it has to match
character for character - no trailing slash, no locale prefix.

| Environment                           | Authorized redirect URI                    |
| ------------------------------------- | ------------------------------------------ |
| Development (`VITNODE_WEB_URL` unset) | `http://localhost:3000/login/sso/google`   |
| Production                            | `https://your-domain.com/login/sso/google` |

Add both. Google allows several redirect URIs per client, and one client for dev
and prod is fine while you are getting started.

{/* Image prompt: The Google Auth Platform "Create OAuth client" form with Application type set to "Web application" and one entry under "Authorized redirect URIs" reading http://localhost:3000/login/sso/google, light theme, 1000x700. */}

<Callout type="warn" title="redirect_uri_mismatch">
  This is the error you will get if the URI differs by so much as a trailing
  slash. It comes from Google, not from VitNode, and it is always this field.
</Callout>

</Step>

<Step>

### Copy the client ID and secret [#copy-the-client-id-and-secret]

Open the client you just created from the **Clients** list. The **Client ID** and
**Client secret** are on the right-hand side of the detail panel. Copy both -
Google will let you see the secret again, but you may as well paste it straight
into `.env`.

{/* Image prompt: The Google Auth Platform OAuth client detail panel with the "Client ID" and "Client secret" fields visible on the right, values redacted, light theme, 1100x600. */}

</Step>

<Step>

### Set the environment variables [#set-the-environment-variables]

These names are not magic - they are whatever you read in your config on the
next step. What matters is that they are server-side variables, so leave them
out of `clientEnv`: that list is what publishes a value to the browser bundle,
and a client secret in the browser bundle is a client secret you have published.

```bash title=".env"
GOOGLE_CLIENT_ID=1234567890-abc.apps.googleusercontent.com # [!code ++]
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxx # [!code ++]
```

</Step>

<Step>

### Register the adapter [#register-the-adapter]

Add `GoogleSSOApiPlugin` to `authorization.ssoAdapters` in your API config.
Note that it is a plain factory function, not a class - there is no `new`.

```ts title="src/vitnode.api.config.ts"
import { GoogleSSOApiPlugin } from '@vitnode/core/api/adapters/sso/google' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

The redirect URI is computed when this file is evaluated, so restart the API
rather than relying on a hot reload:

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

</Step>

<Step>

### Verify it works [#verify-it-works]

Ask the API what it thinks it supports:

```bash
curl http://localhost:3000/api/@vitnode/core/middleware
# {"isEmail":false,"sso":[{"id":"google","name":"Google"}]}
```

Then open `/login` and press **Google**. You should be sent to Google's consent
screen, bounced back to `/login/sso/google?code=...&state=...`, and land on the
front page signed in. Your account now has a row in `core_users_sso` with
`providerId` `google`.

{/* Image prompt: The VitNode /login page with the email and password fields above a divider reading "Or continue With" and an outline button labelled Google beneath it, light theme, 900x850. */}

</Step>

<Step>

### Publish the app [#publish-the-app]

While the client is unpublished, Google restricts sign-in to the test users you
listed and shows an "unverified app" warning. Once the round trip works, go to
**Google Auth Platform → Audience** and press **Publish app**.

{/* Image prompt: The Google Auth Platform "Audience" page showing publishing status "Testing" with the "Publish app" button highlighted, light theme, 1000x500. */}

</Step>

</Steps>

## What the adapter asks Google for [#what-the-adapter-asks-google-for]

Useful when you are debugging a consent screen that shows more or fewer
permissions than you expected.

| Setting       | Value                                           |
| ------------- | ----------------------------------------------- |
| Authorize URL | `https://accounts.google.com/o/oauth2/auth`     |
| Token URL     | `https://oauth2.googleapis.com/token`           |
| Profile URL   | `https://www.googleapis.com/oauth2/v1/userinfo` |
| Scopes        | `openid profile email`                          |
| Provider id   | `google`                                        |
| Fields read   | `id`, `email`, `name`, `verified_email`, `given_name`, `family_name`, `picture` |

The account name VitNode creates comes from Google's `name` field, stripped of
characters that cannot appear in a profile URL.

`given_name`, `family_name` and `picture` come with the `profile` scope Google
already asks for, so [Connected accounts](/docs/dev/sso/connected-accounts) can
import all three with no extra permission. Google never guarantees them - an
account without one simply has nothing to import for that field.

## Gotchas [#gotchas]

<Callout type="warn" title="Unverified Google emails are rejected">
  The adapter reads `verified_email` and throws a `400` when it is `false`, so a
  Google account with an unconfirmed address cannot sign in at all. The visitor
  sees the generic error screen rather than an explanation, which is the one
  place this is worth knowing about in advance.
</Callout>

<Callout type="warn" title="A missing key fails on click, not on boot">
  A `GoogleSSOApiPlugin` whose `clientId` is `undefined` registers happily - the
  button renders and the provider is listed - and throws `Missing Google client
  ID` the moment somebody presses it. If the button is there but does nothing
  except raise an error toast, check the environment before you check the
  console.
</Callout>

## Next [#next]

# Provider Icons and Colors (/docs/dev/sso/icons)

Every SSO provider gets a full-width **Continue with _Provider_** button on
`/login` and `/register`. The built-in Google, Discord and Facebook adapters
already carry their brand marks and colors, so those buttons look right without
any configuration. A custom adapter starts out as a neutral button with
text only - a **GitHub** button with no octocat - and this page shows how to
give it a mark and a color.

## From the adapter (SVG or image) [#from-the-adapter-svg-or-image]

Add an `icon` to whatever your adapter returns. It travels to the browser with
the rest of the provider list, so it has to be a string: inline SVG markup, or a
URL the browser can load as an image.

```ts title="apps/api/src/utils/sso/github.ts"
export const GitHubSSOApiPlugin = (): SSOApiPlugin => ({
  id: 'github',
  name: 'GitHub',
  // [!code ++]
  icon: '<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12" /></svg>',
  // ... getUrl, fetchToken, fetchUser
})
```

Use `fill="currentColor"` and leave the width and height off: the mark then
takes the button's text color in both light and dark mode - white on a
[brand-colored button](#brand-color) - and is sized to match the label. A
multicolor mark, such as Google's four-color G, keeps its own fills; give its
adapter no brand color so it sits on the neutral button it was designed for.

An image works the same way:

```ts
icon: 'https://cdn.example.com/brands/slack.svg' // remote file
icon: '/icons/slack.png' // something in your app's public folder
icon: 'data:image/png;base64,iVBORw0KGgo...' // inlined bytes
```

The markup is inserted into the page, so it is checked before it renders:

- inline markup must be a single `<svg>...</svg>` element - an XML prolog,
  a `DOCTYPE` and comments around it are fine and get stripped,
- nothing executable - no `<script>`, no `onload`-style attributes, no
  `javascript:` URLs, no `<foreignObject>`, and no `<style>` block (a `<style>`
  inside inline SVG is not scoped, so it would restyle the whole page),
- image URLs must be `https:`, `http:`, a root-relative path (`/icons/x.png`),
  or a `data:image/...` URI,
- at most 16 KB.

An icon that fails any of those is dropped. The button keeps its name and still
signs people in - you lose the mark, never the provider. In development the
console says which provider's icon was dropped, so a silent button is never a
mystery.

</Callout>

### Importing an .svg file [#importing-an-svg-file]

You do not have to paste the markup. Where the adapter is bundled by Vite -
`apps/web`, or any generated VitNode app - import the file itself:

```ts title="apps/web/src/vitnode.api.config.ts"
import githubIcon from './icons/github.svg?raw' // the file's markup
import slackIcon from './icons/slack.svg' // the file's URL

export const vitNodeApiConfig = buildApiConfig({
  authorization: {
    ssoAdapters: [
      GitHubSSOApiPlugin({ icon: githubIcon }),
      SlackSSOApiPlugin({ icon: slackIcon }),
    ],
  },
  // ...
})
```

Both work: `?raw` hands you the file's contents - prolog, `DOCTYPE`, generator
comment and all - and a plain import hands you a URL (`/assets/slack-a1b2c3.svg`
after a build, or an inlined `data:image/svg+xml,...` for a small file). Prefer
`?raw` when you want the mark to follow the button's text colour, since a file
loaded through `<img>` cannot see `currentColor`.

A standalone API app such as `apps/api` runs on Node with no bundler, so an
`import` of an `.svg` is not a module there. Read the file instead:

```ts title="apps/api/src/utils/sso/github.ts"
import { readFileSync } from 'node:fs'

const githubIcon = readFileSync(
  new URL('./github.svg', import.meta.url),
  'utf8',
)
```

Read it once at module scope, not inside `getUrl` - and remember `tsc` does not
copy `.svg` files into `dist`, so either copy it as part of your build or keep
the markup in a `.ts` constant, the way VitNode's own adapters do.

If you would rather have a component than a string, register it in the browser
instead - see [From the browser](#from-the-browser-react-component-or-jsx).

## Brand color [#brand-color]

Add a `brandColor` to fill the button with the provider's color, the way the
built-in Discord (`#5865F2`) and Facebook (`#0866FF`) adapters do:

```ts title="apps/api/src/utils/sso/github.ts"
export const GitHubSSOApiPlugin = (): SSOApiPlugin => ({
  id: 'github',
  name: 'GitHub',
  icon: githubIcon,
  // [!code ++]
  brandColor: '#24292F',
  // ... getUrl, fetchToken, fetchUser
})
```

The value has to be a hex color - `#RGB` or `#RRGGBB`. The button picks its
own text color: white when white text reaches a 4.5:1 contrast ratio on your
color, near-black otherwise, so a yellow brand still gets a readable label. A
`currentColor` icon follows that text color.

Leave `brandColor` out and the button stays neutral, with a border. That is the
right choice for providers whose guidelines ask for a neutral button, such as
Google and Microsoft. A value that is not a hex color is ignored the same way,
and in development the console names the provider.

## From the browser (React component or JSX) [#from-the-browser-react-component-or-jsx]

If you would rather ship an icon as a component - a `lucide-react` icon, a
component from your own design system, or plain JSX - register it by provider
id. A registered icon wins over whatever the adapter sent.

```tsx title="apps/web/src/router.tsx"
import { configureSSOIcons } from '@vitnode/core/tanstack/auth'

import { GitHubIcon } from './components/icons/github'

configureSSOIcons({
  github: GitHubIcon, // a component: rendered with `className="size-4"`
  slack: <img alt="" className="size-4" src="/icons/slack.png" />, // or JSX
})
```

Call it from a module your router entry imports, so it has run before the login
screen renders. `configureSSOIcons` merges, so you can call it more than once -
once per plugin, if that suits you.

This is also the escape hatch for a provider whose mark you cannot express as
one static SVG: an animated logo, a theme-aware pair of files, or an icon that
needs a wrapper element.

## Reference [#reference]

# Single Sign-On (SSO) (/docs/dev/sso)

VitNode provides built-in OAuth2 single sign-on. Register an adapter in your API configuration, and authentication buttons automatically appear on `/login` and `/register`.

## Quick start [#quick-start]

```ts title="apps/api/src/vitnode.api.config.ts"
import { GoogleSSOApiPlugin } from "@vitnode/core/api/adapters/sso/google"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  // [!code ++:8]
  authorization: {
    ssoAdapters: [
      GoogleSSOApiPlugin({
        clientId: process.env.GOOGLE_CLIENT_ID!,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      }),
    ],
  },
})
```

A **Continue with Google** button automatically renders on your login and
registration forms, four-color G included. The built-in adapters ship their own
marks and colors - Discord and Facebook buttons are filled with their brand
color - and a custom adapter can [add its own](/docs/dev/sso/icons).

---

## Supported Providers [#supported-providers]

---

## Callback URLs [#callback-urls]

When configuring OAuth2 applications in provider developer consoles, use the following redirect URI pattern:

```text
https://your-domain.com/login/sso/{provider_id}
```

For example: `https://your-domain.com/login/sso/google`.

---

## How Accounts Link [#how-accounts-link]

When a user signs in via SSO:
1. **Known Identity**: The provider account was linked before, so the user is signed straight into it.
2. **Existing Email Match**: An account already uses that address. The visitor is asked for that account's password; once it checks out, the provider identity is linked to the account and they are signed in. From then on that provider signs them straight in (case 1). A social login can never take over an account on its own - the password is what proves ownership.
3. **New Visitor**: A new user is created with their social display name and email. Avatar and real name stay empty until the member imports them from [Connected accounts](/docs/dev/sso/connected-accounts).

Signed-in members can also connect more providers, import their avatar and name, and disconnect accounts in **Settings → Connected accounts** - see [Connected Accounts](/docs/dev/sso/connected-accounts).

### SSO confirms the email [#sso-confirms-the-email]

A provider only hands VitNode an address it has verified itself (the built-in
adapters refuse anything else), so a social sign-in doubles as email
confirmation:

- a **new visitor** starts out with `emailVerified: true`, even when an email
  adapter is configured and password sign-ups would have to confirm first;
- a **known identity** or a **freshly linked** account whose address is still
  unconfirmed is marked confirmed - provided the address the provider returned
  is the one on the account. An account whose email was changed since the link
  was made is left alone.

### Linking an existing account [#linking-an-existing-account]

The callback answers `409` with a short-lived, signed **link offer** - the
account's email, whether it has a password, and a token good for ten minutes.
The login page turns that into a "Connect *Provider* to your account" form: the
email is shown read-only, the visitor types their password, and
`POST /users/sso/{providerId}/link` verifies both before it writes the
`core_users_sso` row and mints a session. The token carries the provider account
id, so nothing about *which* identity gets linked is taken from the browser.

An account created by another provider has no password to confirm with. When an
email adapter is configured the form offers **Set a password** (the ordinary
reset flow) and asks them to try the provider again afterwards; without one it
points back to the login page.

Every successful link emits [`user.sso.linked`](/docs/dev/events/built-in-events).

The address the provider returns is matched in its canonical form, so a Google account that reports `jan.kowalski@gmail.com` finds the member who registered as `jankowalski@gmail.com` instead of quietly becoming a second account. See [One Mailbox, One Account](/docs/dev/advanced/auth#one-mailbox-one-account).

## Learn More [#learn-more]

# Using connected accounts (/docs/dev/sso/using-connected-accounts)

Connected accounts let you sign in with an account you already have, like Google or Discord. They can also fill in your avatar and name so you don't have to - but only when you say so.

## Connect an account [#connect-an-account]

1. Open your avatar menu, go to **Settings**, then **Connected accounts**.
2. Find the provider under **Sign-in accounts** and select **Connect**.
3. Sign in at the provider and allow access.
4. You're back in settings with "Account connected". From now on you can use that button on the login page.

Your email here never changes, even if the provider account uses a different one. Each provider account can belong to one member only, and you can connect one account per provider.

## Import your avatar or name [#import-your-avatar-or-name]

1. Select **Import avatar and name** (or **Import avatar**, depending on what the provider shares) next to the account under **Sign-in accounts**.
2. Pick what to bring over - avatar, first name, last name - and select **Continue**.
3. Confirm it's you at the provider.
4. Review the values, untick anything you don't want, and select **Import selected**.

Nothing changes until that last step. If the provider didn't share something, your current value stays as it is. Importing your name doesn't switch on "Show my real name".

## Keep it up to date [#keep-it-up-to-date]

1. Under **Profile**, pick where each field comes from - for example "From Google" for your avatar. It saves right away.
2. Under **Sync**, select **Sync now** next to that account. You confirm it's you at the provider and land right back in settings with your profile updated. You stay signed in the whole time.
3. Want it automatic? Turn on **On sign-in** for that account.

Each field follows one account at a time, and different fields can follow different accounts.

Changed your mind and edited your name or avatar yourself? That field switches back to manual, so the next sync won't overwrite it.

## Disconnect an account [#disconnect-an-account]

Select **Disconnect** next to the account under **Sign-in accounts** and confirm. You can't sign in with that account anymore, and its sync settings are gone. Your avatar and name stay as they are.

The provider still lists this site as a connected app until you remove it in your provider account settings.

<Callout type="warn">
  If that account is your only way in, you'll see "Keep a way to sign in".
  Set a password with **Forgot password?** on the login page, add a passkey
  under **Security**, or connect another account first.
</Callout>

# Custom adapter (/docs/dev/storage/custom-adapter)

A storage adapter is a plain factory that returns three functions. VitNode has
already validated the file, re-encoded the image and built a collision-free key
before it calls you - your job is to put bytes somewhere and be able to name
their URL afterwards.

## Quick start [#quick-start]

The whole contract is one interface, and there is nothing to install to
implement it:

```ts title="packages/vitnode/src/api/models/storage.ts"
export interface StorageApiPlugin {
  delete: (key: string) => Promise<void>
  getUrl: (key: string) => string
  static?: StorageStaticConfig
  upload: (args: StorageUploadArgs) => Promise<StorageUploadResult>
}
```

Return an object of that shape from a factory, set it as `storage.adapter` in
your API config, and VitNode stores files through it. The
[working skeleton](#write-one) below is about 60 lines.

## The three methods [#the-three-methods]

| Method                               | Gets                                                   | Must return                     | Rules                                                                        |
| :----------------------------------- | :----------------------------------------------------- | :------------------------------ | :--------------------------------------------------------------------------- |
| `upload({ key, body, contentType })` | A Node `Buffer`, the media type, and a pre-built `key` | `{ key, url }`                  | Store `body` **at that exact key**. The key is written to the database as-is |
| `delete(key)`                        | The key from the `core_files` row                      | `Promise<void>`                 | An object that is already gone is a success, not an error                    |
| `getUrl(key)`                        | The same key                                           | A public URL, **synchronously** | Build a string. No network, no `await` - it runs once per row in a listing   |

`StorageUploadArgs` and `StorageUploadResult` are exported from the same module,
so you never have to restate them:

```ts title="packages/vitnode/src/api/models/storage.ts"
export interface StorageUploadArgs {
  body: Buffer
  contentType?: string
  key: string
}

export interface StorageUploadResult {
  key: string
  url: string
}
```

## Write one [#write-one]

### Write the adapter [#write-the-adapter]

A complete adapter, against any object store that answers `PUT` and `DELETE` and
serves the objects back from a public base URL. Both official cloud adapters
default their arguments to `""` and check them lazily, so a missing environment
variable fails on the first upload with a sentence rather than at import time
with a stack trace.

```ts title="src/utils/storage/http-storage.ts"
import type {
  StorageApiPlugin,
  StorageUploadArgs,
  StorageUploadResult,
} from '@vitnode/core/api/models/storage'

export const HttpStorageAdapter = ({
  apiKey = '',
  endpoint = '',
  publicUrl = '',
}: {
  apiKey: string | undefined
  endpoint: string | undefined
  publicUrl: string | undefined
}): StorageApiPlugin => {
  const requireConfig = () => {
    if (!(apiKey && endpoint && publicUrl)) {
      throw new Error('Missing HTTP storage configuration')
    }

return { apiKey, endpoint: endpoint.replace(/\/$/, '') }
  }

const getUrl = (key: string): string =>
    `${publicUrl.replace(/\/$/, '')}/${key}`

return {
    getUrl,
    delete: async (key: string): Promise<void> => {
      const { apiKey, endpoint } = requireConfig()

const res = await fetch(`${endpoint}/${key}`, {
        method: 'DELETE',
        headers: { Authorization: `Bearer ${apiKey}` },
      })
      if (!res.ok && res.status !== 404) {
        throw new Error(`Storage delete failed with ${res.status}`)
      }
    },
    upload: async ({
      body,
      contentType,
      key,
    }: StorageUploadArgs): Promise<StorageUploadResult> => {
      const { apiKey, endpoint } = requireConfig()

const res = await fetch(`${endpoint}/${key}`, {
        method: 'PUT',
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': contentType ?? 'application/octet-stream',
        },
        body: new Uint8Array(body),
      })
      if (!res.ok) {
        throw new Error(`Storage upload failed with ${res.status}`)
      }

return { key, url: getUrl(key) }
    },
  }
}
```

Two details worth copying rather than reinventing. `delete` treats a `404` as
done, because `deleteFile` has already removed the database row by the time it
runs - throwing there turns a finished delete into a failed request. And
`upload` returns the key it was handed, never a rewritten one.

</Step>
<Step>

### Register it [#register-it]

An adapter needs no registry, no manifest and no plugin entry. It is a value on
the API config:

```ts title="src/vitnode.api.config.ts"
import { buildApiConfig } from '@vitnode/core/vitnode.config'

import { HttpStorageAdapter } from './utils/storage/http-storage' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    // [!code ++:5]
    adapter: HttpStorageAdapter({
      apiKey: process.env.STORAGE_API_KEY,
      endpoint: process.env.STORAGE_ENDPOINT,
      publicUrl: process.env.STORAGE_PUBLIC_URL,
    }),
  },
})
```

</Step>
<Step>

### Verify it round-trips [#verify-it-round-trips]

Open **AdminCP → Core → System → Integrations** (`/admin/core/system/integrations`)
and click **Test storage** on the Storage card. It uploads an image through your
adapter, then the row shows up in **AdminCP → Core → System → Files** with a
working thumbnail - which is `getUrl` proving itself, since the browser loads
that URL directly.

If the thumbnail is broken but the upload succeeded, `upload` and `getUrl`
disagree about the URL. If the upload itself failed, the API log has your own
error message in it.

</Step>
</Steps>

<Callout type="info" title="Keys are pre-built for you">
  The framework builds `{year}/{month}/{folder}/<uuid>.<ext>` before
  calling `upload`, checks every folder segment against the traversal guard, and
  stores that key on the `core_files` row. So an adapter stores `body` at the
  key it was handed and never invents path logic - see [storage
  keys](/docs/dev/storage#storage-keys).
</Callout>

## The optional static descriptor [#the-optional-static-descriptor]

Disk-backed adapters can expose a fourth field, and only they should:

```ts
export interface StorageStaticConfig {
  mountPath: string
  root: string
  stripPrefix: string
}
```

It is not read by the storage layer at all - the app that boots the API reads it
to mount Hono's `serveStatic` for the stored files, which is how the
[Local adapter](/docs/dev/storage/local#serve-the-stored-files) serves what it
writes. A cloud adapter omits it, and the mount is then skipped.

| Field         | The Local adapter's value                              |
| :------------ | :----------------------------------------------------- |
| `mountPath`   | `publicPath` with a leading `/api` stripped, plus `/*` |
| `root`        | `./public/uploads`                                     |
| `stripPrefix` | `publicPath`, e.g. `/api/uploads`                      |

## Gotchas [#gotchas]

<Callout type="warn" title="A thrown error becomes a 500">
  Your errors are not `HTTPException`s, so the API's error handler answers `500`
  - with your message in the body during development and a bare "Internal Server
  Error" in production, where only the log has the reason. That is the same deal
  the official adapters get. Throw an `HTTPException` from `hono/http-exception`
  instead when the person uploading can act on the cause - a quota, say, rather
  than a broken token.
</Callout>

<Callout type="warn" title="getUrl runs once per row">
  The AdminCP Files table calls it for every file on the page, and it is
  declared synchronous, so a signed URL that needs a round trip does not fit
  here. Put a CDN or a public base URL in front of the store and build a string.
</Callout>

<Callout type="warn" title="Never rewrite the key">
  Returning a different `key` than you were given stores that value on the row -
  and every later read, download and delete uses it. If your provider mangles
  the path (a leading slash, a normalised case), return the key **as the
  provider will accept it back**, not as you wish it were.
</Callout>

<Callout type="info" title="Sizes and dimensions are already decided">
  `body.length` is what lands in `core_files.size`, and the image pipeline has
  already run. An adapter that compresses further would make the database
  disagree with the object, so leave the bytes alone.
</Callout>

## Publish it [#publish-it]

If the adapter is useful to more than one installation, publish it as a package.
Both official adapters are small enough to read in one sitting and are the best
starting template:

- [`@vitnode/s3`](https://github.com/aXenDeveloper/vitnode/tree/canary/packages/s3) -
  a lazily created SDK client, a URL built from three rules
- [`@vitnode/supabase-storage`](https://github.com/aXenDeveloper/vitnode/tree/canary/packages/supabase-storage) -
  the shortest possible adapter, at under 60 lines

Keep `@vitnode/core` a dev dependency (you only import types from it) and ship
your provider's SDK as a real dependency, the way both of those do.

## Next [#next]

# Storage (/docs/dev/storage)

VitNode provides an integrated storage layer accessible via `c.get("storage")`. It handles file validation, automatic WebP image optimization, database indexing in `core_files`, and persistent storage across multiple backends.

## Quick start [#quick-start]

### 1. Register a Storage Adapter [#1-register-a-storage-adapter]

In `apps/api/src/vitnode.api.config.ts`, configure the local disk adapter:

```ts title="apps/api/src/vitnode.api.config.ts"
import { LocalStorageAdapter } from "@vitnode/core/api/adapters/storage/local"
import { buildApiConfig } from "@vitnode/core/vitnode.config"

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    adapter: LocalStorageAdapter(), // [!code ++]
  },
})
```

### 2. Upload Files in an API Route [#2-upload-files-in-an-api-route]

Handle uploads in a Hono route using `c.get("storage").upload()`:

```ts title="plugins/blog/src/api/modules/posts/routes/upload-cover.route.ts"
import { z } from "@hono/zod-openapi"
import { buildRoute } from "@vitnode/core/api/lib/route"

export const uploadCoverRoute = buildRoute({
  pluginId: "blog",
  route: {
    method: "post",
    path: "/cover",
    request: {
      body: {
        content: {
          "multipart/form-data": {
            schema: z.object({
              file: z.instanceof(File),
            }),
          },
        },
      },
    },
  },
  handler: async (c) => {
    const { file } = await c.req.parseBody()

// [!code ++:7]
    const uploaded = await c.get("storage").upload({
      file: file as File,
      folder: "covers",
      maxBytes: 5 * 1024 * 1024, // 5 MB
      allowedMimeTypes: ["image/jpeg", "image/png", "image/webp"],
    })

return c.json(uploaded)
  },
})
```

`upload()` saves the file, creates a record in `core_files`, and returns `{ id, url, width, height, size }`.

---

## Supported Storage Adapters [#supported-storage-adapters]

---

## Image Optimization [#image-optimization]

Turn on `storage.image` and VitNode re-encodes JPEG, PNG, AVIF, TIFF and WebP uploads with [sharp](https://sharp.pixelplumbing.com/), converts them to WebP, and records their pixel dimensions:

```ts title="apps/api/src/vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  storage: {
    adapter: LocalStorageAdapter(),
    // [!code ++:5]
    image: {
      quality: 85, // 1-100, defaults to 85
      webp: true, // set to false to keep the original format
      maxPixels: 40_000_000, // width x height, defaults to 40 million
    },
  },
})
```

`maxPixels` is your guard against image bombs - a tiny PNG that claims to be 16383x16383 pixels and unpacks into gigabytes of memory. Anything over the limit is refused with a `400` before a single pixel is decoded. The default fits an 8K photo with room to spare, so most installs never need to touch it.

### What gets checked on every upload [#what-gets-checked-on-every-upload]

Whether or not `storage.image` is set, an upload declared as JPEG, PNG, WebP, GIF, AVIF or TIFF must actually _be_ that format. The type a client sends is just a claim (a browser guesses it from the file name), so VitNode reads the file's first bytes and refuses a mismatch - say, an HTML page named `cat.gif` - with a `400`. SVG and non-image files have no fixed signature and are not affected; limit them with `allowedMimeTypes`.

---

## Deleting Files [#deleting-files]

Remove files and clean up storage using `delete()`:

```ts
await c.get("storage").delete({ fileId: 42 })
```

This removes the file from the configured storage bucket and deletes its row from `core_files`.

---

## Verifying in AdminCP [#verifying-in-admincp]

{/* Image prompt: VitNode AdminCP System -> Integrations screen at /admin/core/system/integrations. Storage integration card shows "Active" with a "Test file storage" button and modal demonstrating test file upload. Dark theme, 1440x900. */}

Test your storage adapter anytime in the AdminCP:
1. Navigate to **System → Integrations** (`/admin/core/system/integrations`).
2. On the **Storage** card, click **Test Storage** to verify bucket credentials and upload capabilities.
3. Inspect uploaded files anytime under **System → Files** (`/admin/core/system/files`).

## Learn More [#learn-more]

# Local (disk) (/docs/dev/storage/local)

The Local adapter is the one that needs no account, no keys and no extra package:
it writes uploads into `public/uploads` next to your API and serves them back as
static files. Perfect for development and for a single self-hosted server, and
the wrong choice on serverless.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { LocalStorageAdapter } from '@vitnode/core/api/adapters/storage/local' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    adapter: LocalStorageAdapter(), // [!code ++]
  },
})
```

That is enough to store files. Serving them back is one more step, and it depends
on which app runs the API - keep reading.

## Set it up [#set-it-up]

### Register the adapter [#register-the-adapter]

There is nothing to install - the adapter lives in `@vitnode/core`, which you
already depend on. Import it and set `storage.adapter`, exactly as in the
[Quick start](#quick-start) above.

Uploads then land under the current working directory of the API process:

</Step>
<Step>

### Serve the stored files [#serve-the-stored-files]

Writing a file is not the same as answering a request for it. The adapter exposes
a `static` descriptor - `mountPath`, `root` and `stripPrefix` - so the mount is
derived from your `publicPath` instead of hardcoded in two places.

```ts tab="Standalone API" title="apps/api/src/index.ts"
import { serveStatic } from '@hono/node-server/serve-static'
import { storageStaticHeadersMiddleware } from '@vitnode/core/api/middlewares/storage-static.middleware'
import { mkdirSync } from 'node:fs'

// [!code ++:15]
const staticStorage = vitNodeApiConfig.storage?.adapter?.static
if (staticStorage) {
  mkdirSync(staticStorage.root, { recursive: true })
  app.get(
    staticStorage.mountPath,
    storageStaticHeadersMiddleware(),
    serveStatic({
      root: staticStorage.root,
      rewriteRequestPath: (path) =>
        path.startsWith(staticStorage.stripPrefix)
          ? path.slice(staticStorage.stripPrefix.length)
          : path,
    }),
  )
}

VitNodeAPI({ app, vitNodeApiConfig })
```

```ts tab="TanStack Start app" title="src/server/vitnode-api.server.ts"
import { serveStatic } from '@hono/node-server/serve-static'
import { storageStaticHeadersMiddleware } from '@vitnode/core/api/middlewares/storage-static.middleware'
import { mkdirSync } from 'node:fs'

const createVitNodeApi = () => {
  const app = new OpenAPIHono().basePath('/api')

// [!code ++:15]
  const staticStorage = vitNodeApiConfig.storage?.adapter?.static
  if (staticStorage) {
    mkdirSync(staticStorage.root, { recursive: true })
    app.get(
      staticStorage.mountPath,
      storageStaticHeadersMiddleware(),
      serveStatic({
        root: staticStorage.root,
        rewriteRequestPath: (path) =>
          path.startsWith(staticStorage.stripPrefix)
            ? path.slice(staticStorage.stripPrefix.length)
            : path,
      }),
    )
  }

VitNodeAPI({ app, vitNodeApiConfig })

return app
}
```

</Tabs>

Mount `serveStatic` **before** `VitNodeAPI` on the standalone API: the request
then skips the CORS, CSRF, rate-limiter and global middleware, which a static
image has no use for. `mkdirSync` is only there so `serveStatic` does not warn
about a missing root before the first upload.

<Callout type="warn" title="Keep storageStaticHeadersMiddleware() in front of serveStatic">
  Local uploads are served from your own origin - the one your session cookie
  lives on. Without this middleware, an uploaded SVG or HTML file opened
  directly in the browser runs its script **as your site**, signed in as
  whoever clicked the link. The middleware adds `Content-Security-Policy:
  sandbox` and `X-Content-Type-Options: nosniff`, so stored files can still be
  shown in an `<img>` but never execute. It costs nothing - leave it in.
</Callout>

The TanStack Start app is the same code in a different file, because `/api/*` on
that app is one catch-all route handing the request to the very same Hono
application - so the mount belongs inside it, not in the router. `serveStatic`
comes from `@hono/node-server`, which that app does not depend on yet:

```bash tab="bun"
bun i @hono/node-server
```

```bash tab="pnpm"
pnpm i @hono/node-server
```

```bash tab="npm"
npm i @hono/node-server
```

</Tabs>

<Callout type="warn" title="Vite's public/ is a build-time snapshot">
  During `vite dev` the app's `public/` directory is served at the site root, so
  setting `publicPath: "/uploads"` looks like it works with no mount at all.
  `vite build` copies `public/` into the build output **once**, so files
  uploaded at runtime are written somewhere the production server never reads
  from. Keep the default `publicPath` and mount the `static` descriptor as
  above, or use a cloud adapter - which is the honest answer for anything with
  more than one instance.
</Callout>

</Step>
<Step>

### Point the URLs at the right origin [#point-the-urls-at-the-right-origin]

The adapter builds absolute URLs as `{baseUrl}/{publicPath}/{key}`. `baseUrl`
defaults to the configured API origin, so this env var is what decides whether
your file URLs are reachable:

| Variable          | Required    | What it is for                                                                                                                                                             |
| :---------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VITNODE_API_URL` | Recommended | The public origin of the API. Used as the default `baseUrl`, so a wrong value produces URLs that 404. Falls back to the browser's own origin, then `http://localhost:3000` |

```bash title=".env"
VITNODE_API_URL=http://localhost:8000
```

Pass `baseUrl` explicitly if the files are fronted by a different hostname than
the API itself.

</Step>
<Step>

### Upload something and verify [#upload-something-and-verify]

Open **AdminCP → Core → System → Integrations** and use **Test storage** on the
Storage card: it uploads an image and tells you whether the round trip worked.

Then check the file is really on disk and really served:

```bash
ls public/uploads
curl -I http://localhost:8000/api/uploads/2026/09/admin-storage-test/<uuid>.webp
```

A `200` means the mount is right. A `404` with the file present on disk means the
`publicPath` and the mount disagree.

</Step>
</Steps>

## Options [#options]

The default `publicPath` is `/api/uploads` because the API mounts everything under
`/api`, and `mountPath` strips that prefix back off so the route is registered
once, in the right place. Change `publicPath` and the descriptor follows it - but
keep it under `/api`: `stripPrefix` is the whole `publicPath`, so a `publicPath`
outside the API's own base path strips nothing and every file answers `404`.

## Gotchas [#gotchas]

<Callout type="warn" title="Not durable on serverless">
  Serverless platforms give every instance an ephemeral filesystem. Files
  written by one instance are invisible to the next and gone after a deploy,
  which shows up as images that worked this morning. Use [S3 or
  R2](/docs/dev/storage/s3-r2) or [Supabase Storage](/docs/dev/storage/supabase)
  there.
</Callout>

<Callout type="warn" title="Relative to the process, not to the file">
  The upload path is resolved from `process.cwd()`, so starting the API from a
  different directory points it at a different `public/uploads`. Old files do
  not disappear - the keys on the `core_files` rows still name them - but the
  new directory answers the requests.
</Callout>

<Callout type="warn" title="A missing file is a 404, not a repaired row">
  Deleting a file from disk by hand leaves its `core_files` row behind, and the
  AdminCP Files table will keep listing it with a broken preview. Delete through
  the table (or `deleteFile`) so the row and the bytes go together.
</Callout>

<Callout type="info" title="Back it up like a database">
  `public/uploads` is state. A container that recreates its filesystem on deploy
  loses every upload, and no `core_files` row can bring the bytes back. Mount a
  volume, or move to a cloud adapter.
</Callout>

## Next [#next]

# AWS S3 / Cloudflare R2 (/docs/dev/storage/s3-r2)

`@vitnode/s3` puts your uploads in an object store instead of on the API's disk,
which is what you want the moment there is more than one server - or no server
you own at all. R2 is S3-compatible, so the same adapter covers both: you add an
`endpoint` and you are done.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { S3StorageAdapter } from '@vitnode/s3' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    // [!code ++:6]
    adapter: S3StorageAdapter({
      bucket: process.env.S3_BUCKET,
      region: process.env.S3_REGION,
      accessKeyId: process.env.S3_ACCESS_KEY_ID,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    }),
  },
})
```

## Set it up [#set-it-up]

### Install the adapter [#install-the-adapter]

```bash tab="bun"
bun i @vitnode/s3
```

```bash tab="pnpm"
pnpm i @vitnode/s3
```

```bash tab="npm"
npm i @vitnode/s3
```

</Tabs>

It is a runtime dependency of the app that serves your API, not a dev
dependency - the API imports it on every boot. `@aws-sdk/client-s3` comes with
it, so there is nothing else to add.

</Step>
<Step>

### Create the bucket and an access key [#create-the-bucket-and-an-access-key]

1. In the S3 console, create a bucket and note its **name** and **region**.
2. In IAM, create a user (or role) with `s3:PutObject`, `s3:DeleteObject` and
   `s3:GetObject` on `arn:aws:s3:::your-bucket/*`, then create an access key.
3. Copy the **Access key ID** and **Secret access key**. The secret is shown once.

{/* Image prompt: The AWS IAM console "Retrieve access key" screen after creating an access key, with the Access key ID visible and the Secret access key revealed but the characters replaced by asterisks, plus the Download .csv button. Light theme, 1440x900. */}

</Tab>

1. In the Cloudflare dashboard, open **R2** and create a bucket.
2. Open **Manage R2 API Tokens** and create a token with **Object Read & Write**
   for that bucket.
3. Copy the **Access Key ID**, the **Secret Access Key** and the
   **S3 API endpoint** - the last one looks like
   `https://<account_id>.r2.cloudflarestorage.com` and is what makes R2 work
   through an S3 client.

{/* Image prompt: The Cloudflare dashboard R2 API token success screen, showing the "Use the following credentials" panel with Access Key ID, Secret Access Key (masked) and the S3 API endpoint URL https://<account_id>.r2.cloudflarestorage.com clearly readable. Dark theme, 1440x900. */}

</Tab>

</Tabs>

</Step>
<Step>

### Put the credentials in the environment [#put-the-credentials-in-the-environment]

The adapter takes plain arguments, so the names are yours to choose. These are
the ones VitNode's own `.env.example` uses, and the ones the snippets here read:

```bash title=".env"
S3_BUCKET=your-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your_access_key_id
S3_SECRET_ACCESS_KEY=your_secret_access_key
# Cloudflare R2 only
# S3_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
# Optional CDN or custom domain in front of the bucket
# S3_PUBLIC_URL=https://cdn.example.com
```

</Step>
<Step>

### Register the adapter [#register-the-adapter]

For AWS S3, the four values above are all it needs:

```ts title="src/vitnode.api.config.ts"
import { S3StorageAdapter } from '@vitnode/s3' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

For Cloudflare R2, keep the same adapter and add the endpoint - the region stays
at its `auto` default:

```ts title="src/vitnode.api.config.ts"
adapter: S3StorageAdapter({
  bucket: process.env.S3_BUCKET,
  accessKeyId: process.env.S3_ACCESS_KEY_ID,
  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
  endpoint: process.env.S3_ENDPOINT, // [!code ++:2]
  publicUrl: process.env.S3_PUBLIC_URL,
}),
```

</Step>
<Step>

### Upload a test file [#upload-a-test-file]

Open **AdminCP → Core → System → Integrations** (`/admin/core/system/integrations`).
The Storage card now reads active; click **Test storage** and upload an image.

On success the dialog says the image is stored in your adapter, and the object
appears in the bucket under `{year}/{month}/admin-storage-test/…`. On
failure, check the API logs: the SDK's own error names the cause, and the two
usual suspects are a bucket in a different region than `S3_REGION` and a token
without write permission.

The file also shows up in **AdminCP → Core → System → Files** with its size and
pixel dimensions - proof that both the object and its `core_files` row were
written.

</Step>
</Steps>

## How the public URL is built [#how-the-public-url-is-built]

`getUrl` never asks the provider - it builds a string, and the first rule that
applies wins:

| Condition          | Resulting URL                                      |
| :----------------- | :------------------------------------------------- |
| `publicUrl` is set | `{publicUrl}/{key}`                                |
| `endpoint` is set  | `{endpoint}/{bucket}/{key}`                        |
| Neither            | `https://{bucket}.s3.{region}.amazonaws.com/{key}` |

For R2 that middle row matters: the S3 API endpoint is **not** a public read
domain, so a bucket without a public `r2.dev` or custom domain gives URLs that
only your credentials can read. Enable public access on the bucket and put that
hostname in `publicUrl`.

{/* Image prompt: The Cloudflare R2 bucket "Settings" tab with the "Public Development URL" / custom domain section expanded, showing the r2.dev hostname enabled and a "Connect Domain" button beside it. Dark theme, 1440x900. */}

## Options [#options]

## Gotchas [#gotchas]

<Callout
  type="warn"
  title="Misconfiguration surfaces on the first upload, not at boot"
>
  The S3 client is created lazily, so a missing bucket or key throws `Missing S3
  configuration` the first time somebody uploads - not when the server starts.
  The Integrations card only knows an adapter is *registered*. Run **Test
  storage** after any credential change.
</Callout>

<Callout type="warn" title="A private bucket breaks previews and downloads">
  VitNode serves files by URL, and the built-in download routes fetch that URL
  server-side before re-streaming it. If neither the bucket nor `publicUrl` is
  publicly readable, thumbnails never load and both download routes turn the
  refused fetch into a `404`. Front the bucket with CloudFront, an R2 custom
  domain, or make it public.
</Callout>

<Callout type="warn" title="A provider error reaches the browser as a 500">
  The adapter lets the SDK's own error propagate, and it is not an
  `HTTPException` - so a denied `PutObject` or a bucket in the wrong region
  answers `500`, with the useful sentence in the API log rather than in the
  uploader. Catch it in your route if the person uploading deserves better than
  "something went wrong".
</Callout>

<Callout type="info" title="Objects are overwritten, never appended">
  Keys contain a UUID, so a collision is not a practical concern - but a
  `PutObject` to an existing key replaces it. If you enable versioning on the
  bucket, remember that `deleteFile` removes the current version only; lifecycle
  rules are how old versions actually go away.
</Callout>

## Next [#next]

# Supabase Storage (/docs/dev/storage/supabase)

`@vitnode/supabase-storage` puts your uploads in a bucket on your Supabase
project. If Supabase is already your database, this is the shortest path off the
local disk: no IAM policy, no endpoint, three values and you are done.

## Quick start [#quick-start]

```ts title="src/vitnode.api.config.ts"
import { SupabaseStorageAdapter } from '@vitnode/supabase-storage' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

export const vitNodeApiConfig = buildApiConfig({
  storage: {
    // [!code ++:5]
    adapter: SupabaseStorageAdapter({
      url: process.env.SUPABASE_URL,
      secretKey: process.env.SUPABASE_SECRET_KEY,
      bucket: process.env.SUPABASE_STORAGE_BUCKET,
    }),
  },
})
```

## Set it up [#set-it-up]

### Install the adapter [#install-the-adapter]

```bash tab="bun"
bun i @vitnode/supabase-storage
```

```bash tab="pnpm"
pnpm i @vitnode/supabase-storage
```

```bash tab="npm"
npm i @vitnode/supabase-storage
```

</Tabs>

A runtime dependency of the app that serves your API, not a dev dependency - the
API imports it on every boot. `@supabase/storage-js` comes with it, so there is
nothing else to add.

</Step>
<Step>

### Create the bucket [#create-the-bucket]

In the Supabase dashboard, open **Storage → Buckets → New bucket**, give it a
name and turn **Public bucket** on. Public is not optional here for anything a
visitor has to see: VitNode serves files by URL, and so do the built-in download
routes - see [the private-bucket gotcha](#gotchas) below.

{/* Image prompt: The Supabase dashboard "New bucket" panel open over the Storage → Buckets list, with a bucket name typed in, the "Public bucket" toggle switched on, and the collapsed "Additional configuration" section showing file size limit and allowed MIME types. Dark theme, 1440x900. */}

Leave the bucket's own **file size limit** and **allowed MIME types** generous
and enforce your real limits in your route with `maxBytes` and
`allowedMimeTypes` - the bucket rejects a file with a Supabase error, your route
rejects it with a sentence somebody can act on.

</Step>
<Step>

### Copy the secret key [#copy-the-secret-key]

Open **Project Settings → API Keys** and copy a **secret key** - the value
starting `sb_secret_`. That is the modern replacement for the legacy
`service_role` key; a still-valid legacy key works too, because the adapter sends
whatever you give it verbatim as the `apikey` and `Authorization: Bearer` header.

{/* Image prompt: The Supabase dashboard Project Settings → API Keys page, showing the publishable key in full and a secret key row with its value masked behind a "Reveal" control and a copy button. Light theme, 1440x900. */}

<Callout type="error" title="A secret key is a server-only key">
  It bypasses row level security, which is exactly why the API can write to the
  bucket. Never put it in client code, a `VITE_*` variable or anything else that
  reaches a browser: a secret key that ships to a visitor is a secret key you
  have to rotate.
</Callout>

</Step>
<Step>

### Put the credentials in the environment [#put-the-credentials-in-the-environment]

The adapter takes plain arguments, so the names are yours. These are the ones the
API configs in this repository read, and the ones the snippets here use:

```bash title=".env"
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SECRET_KEY=sb_secret_...
SUPABASE_STORAGE_BUCKET=your-bucket
```

Miss any one of the three and the first upload throws
`Missing Supabase Storage configuration` - the client is created lazily, so a
typo waits for a file rather than failing at boot.

</Step>
<Step>

### Register the adapter [#register-the-adapter]

```ts title="src/vitnode.api.config.ts"
import { SupabaseStorageAdapter } from '@vitnode/supabase-storage' // [!code ++]
import { buildApiConfig } from '@vitnode/core/vitnode.config'

That is the config `apps/web` in this repository actually runs, image pipeline
included.

</Step>
<Step>

### Upload a test file [#upload-a-test-file]

Open **AdminCP → Core → System → Integrations** (`/admin/core/system/integrations`).
The Storage card now reads active; click **Test storage** and upload an image.

On success the object appears in the bucket under
`{year}/{month}/admin-storage-test/…`, and the row appears in
**AdminCP → Core → System → Files** with its size and pixel dimensions - proof
that both the object and its `core_files` row were written. On failure the API log
carries the Supabase error, and the two usual suspects are a bucket name that does
not exist and a key pasted with its `sb_secret_` prefix trimmed.

</Step>
</Steps>

## How the public URL is built [#how-the-public-url-is-built]

`getUrl` asks `@supabase/storage-js` for the bucket's public URL, which is a
string it builds rather than a request it makes:

```txt
{SUPABASE_URL}/storage/v1/object/public/{bucket}/{key}
```

So every file URL in the installation is that shape, and on a private bucket
Supabase's object API refuses it rather than serving the file - which is why
public matters more here than it looks.

## Options [#options]

## Gotchas [#gotchas]

<Callout type="warn" title="A private bucket breaks previews and downloads">
  `getUrl` returns the bucket's public URL, and the built-in download routes
  fetch that URL server-side before re-streaming it. On a private bucket
  Supabase refuses that URL, so the thumbnails in the AdminCP Files table never
  load and both download routes turn the refused fetch into a `404`. Make the
  bucket public, or front it with a CDN.
</Callout>

<Callout type="warn" title="The bucket's own limits answer with a 500">
  A bucket configured with a file size limit or an allowed-MIME-type list
  rejects the upload inside Supabase, and that error is not an `HTTPException` -
  so it reaches the browser as a `500` with the useful sentence in the API log.
  Set `maxBytes` and `allowedMimeTypes` on your `upload()` call so the refusal
  happens in VitNode, where the message is written for a person.
</Callout>

<Callout type="info" title="Uploads upsert">
  The adapter uploads with `upsert: true`, so writing to an existing key
  replaces it instead of failing. Keys carry a UUID, so this is not a collision
  risk - it is what makes a retried upload idempotent rather than a duplicate.
</Callout>

## Next [#next]

# Swagger (/docs/dev/swagger)

VitNode's API is built on [`@hono/zod-openapi`](https://hono.dev/examples/zod-openapi),
so the Zod schemas a route declares are its documentation. Nothing is written
twice and nothing can drift: if the schema changes, the spec changes, and the
request that no longer matches it is rejected.

## Quick start [#quick-start]

Start the dev server and open Swagger UI in a browser:

| App shape        | Swagger UI                                                             |
| ---------------- | ---------------------------------------------------------------------- |
| **Single App**   | [http://localhost:3000/api/swagger](http://localhost:3000/api/swagger) |
| **Monorepo App** | [http://localhost:8000/api/swagger](http://localhost:8000/api/swagger) |
| **Only API**     | [http://localhost:8000/api/swagger](http://localhost:8000/api/swagger) |

Whichever origin serves `/api/*` serves the UI, because it is a route on the
same Hono app. The raw document is one path deeper, at `/api/swagger/doc` -
OpenAPI 3.0.0, titled `VitNode API`, versioned with the `@vitnode/core` release
you have installed. Point any OpenAPI tool at that URL.

{/* Image prompt: A screenshot of Swagger UI at http://localhost:3000/api/swagger for the VitNode API - the "VitNode API" title bar at the top, and below it collapsed tag groups reading "(Core) - Users", "(Core) - Admin / Users", "(Core) - Admin / Debug" and "(Example) - Content / Articles", with the first group expanded to show a GET and a POST operation. Light theme, 1440x900. */}

Every path reads `/api/{pluginId}/{module}/{route}`, which is why core's session
endpoint is `/api/@vitnode/core/users/session`. That is not a Swagger
convention - it is how the app is mounted, and
[Architecture](/docs/dev/architecture) walks the whole request path.

## Where the spec comes from [#where-the-spec-comes-from]

You never register anything with Swagger. Four steps in the API's own build
produce the document as a side effect:

| Step             | What it contributes                                                                |
| ---------------- | ---------------------------------------------------------------------------------- |
| `buildRoute`     | The operation: method, path, `request` and `responses` schemas, `description`.     |
| `buildModule`    | Registers it on the module's Hono app, and names the group it lands in.            |
| `buildApiPlugin` | Mounts each module under its name and collects the group list for the document.    |
| `VitNodeAPI`     | Mounts each plugin under its `pluginId` and serves `/swagger` plus `/swagger/doc`. |

## Put a plugin route in the spec [#put-a-plugin-route-in-the-spec]

There is no extra work - the same three files that make a route reachable make
it documented. What you control is how good the documentation is.

### Describe the route as you build it [#describe-the-route-as-you-build-it]

`description` becomes the operation's summary line, and every schema field can
carry an `example`. This is the whole difference between a spec people use and a
spec people ignore:

```ts title="src/api/modules/orders/routes/show.route.ts"
import { z } from '@hono/zod-openapi'
import { buildRoute } from '@vitnode/core/api/lib/route'

import { CONFIG_PLUGIN } from '@/const'

export const showOrderRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  route: {
    method: 'get',
    path: '/{id}',
    description: 'Get one order by id', // [!code ++]
    request: {
      params: z.object({
        id: z.string().openapi({ example: '1' }), // [!code ++]
      }),
    },
    responses: {
      200: {
        content: {
          'application/json': {
            schema: z.object({ id: z.string(), total: z.number() }),
          },
        },
        description: 'The order',
      },
    },
  },
  handler: async (c) => c.json({ id: '1', total: 42 }),
})
```

</Step>
<Step>

### Register it in a module [#register-it-in-a-module]

```ts title="src/api/modules/orders/orders.module.ts"
import { buildModule } from '@vitnode/core/api/lib/module'

import { CONFIG_PLUGIN } from '@/const'
import { showOrderRoute } from './routes/show.route'

export const ordersModule = buildModule({
  pluginId: CONFIG_PLUGIN.pluginId,
  name: 'orders', // [!code ++]
  routes: [showOrderRoute], // [!code ++]
})
```

The `name` is the second half of the group heading, so pick the word you want to
read in the sidebar.

</Step>
<Step>

### Mount the module in the plugin [#mount-the-module-in-the-plugin]

```ts title="src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { ordersModule } from '@/api/modules/orders/orders.module'
import { CONFIG_PLUGIN } from '@/const'

export const shopApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    modules: [ordersModule], // [!code ++]
  })
```

</Step>
<Step>

### Reload the UI [#reload-the-ui]

Restart the dev server and refresh `/api/swagger`. A new group is at the bottom
of the list - **(Shop) - Orders** - with `GET /api/@acme/shop/orders/{id}` in
it, and "Try it out" sends a real request with your cookies attached.

</Step>
</Steps>

## Grouping [#grouping]

Swagger has exactly one grouping mechanism - the tag - so the tag carries both
halves of "where does this endpoint live". The plugin comes from `pluginId` with
its scope dropped and title-cased, the module from the `name` you gave
`buildModule`:

```ts
buildModule({
  pluginId: '@vitnode/core', // (Core)
  name: 'users', // - Users
  routes: [sessionRoute],
})
```

A nested module is named after its whole chain, so `(Core) - Admin / Users`
stays a separate group from the top-level `(Core) - Users`:

```ts
buildModule({
  pluginId: '@vitnode/core',
  name: 'admin',
  routes: [],
  modules: [usersAdminModule], // (Core) - Admin / Users
})
```

The chain matters because module names repeat across the tree - core has a
`users` module and an `admin/users` one, plus `cron`, `queue` and `files` twice
over. A leaf-only tag would merge the public and admin halves of each into one
group.

Groups appear in the order the plugins declared their modules, with core first.

<Callout title="Your own tags are kept">
  A route may add `tags` of its own. They survive, after the generated one - so
  the same operation can also show up under a tag you name yourself.
</Callout>

## Gotchas [#gotchas]

<Callout
  type="warn"
  title="Swagger has no login, and it is mounted in production"
>
  `/api/swagger` and `/api/swagger/doc` are registered unconditionally, before
  the session middleware, and neither checks anything. Anyone who can reach your
  API can read every route it serves, including the admin ones. Deny both paths
  at your reverse proxy if that is not what you want - see
  [Self-hosted](/docs/dev/deployments/self-hosted).
</Callout>

<Callout type="warn" title="A response with no content widens res.json() to unknown">
  The [fetcher](/docs/dev/fetcher) infers its return type from the same
  `responses` block Swagger reads. Declare a status with no `content` - a bare
  `401: { description: 'Unauthorized' }` - and there is no response format to
  infer from, so `await res.json()` resolves to `unknown` at every call site.
  Give every documented response a `content` schema, or leave the status
  undeclared and let `HTTPException` produce it.
</Callout>

<Callout type="info" title="The spec is per-installation, not per-package">
  The document lists the plugins **this** app has in its
  `vitnode.api.config.ts`. Install a plugin and its groups appear; remove it and
  they are gone. So `/api/swagger` is a truthful inventory of one deployment
  rather than a catalogue of what VitNode can do.
</Callout>

## Next [#next]

# WebSocket (/docs/dev/websocket)

VitNode provides a unified, multiplexed WebSocket connection at `/api/ws`. Browsers share a single connection across tabs via a Web Lock leader election, authenticated by session cookies.

## Quick start [#quick-start]

### 1. Send a Toast to a User [#1-send-a-toast-to-a-user]

Push a transient toast to any signed-in user from any Hono route or service:

```ts
import { notificationsChannel } from "@vitnode/core/ws/notifications"

// [!code ++:6]
c.get("realtime").sendToUser(userId, notificationsChannel, {
  title: "New Comment",
  description: "Alex commented on your post.",
  type: "info",
})
```

The user receives an immediate `sonner` toast in all open tabs across devices.

<Callout type="info" title="Need it to stick around? Use the Notifications Center">
  `notificationsChannel` is for transient toasts: they reach open tabs only and
  are gone on reload. For anything users should find later - with an inbox,
  unread count, email and preferences - publish a persistent notification with
  `c.get("notifications").publish()`. See
  [Notifications](/docs/dev/notifications). The bell's unread count travels over
  this same connection on `notificationsStateChannel`.
</Callout>

---

### 2. Broadcast to Everyone [#2-broadcast-to-everyone]

Broadcast live updates to all connected visitors:

```ts
c.get("realtime").broadcast(myChannel, {
  count: 142,
})
```

---

## Define a Custom Channel [#define-a-custom-channel]

Create typed channels in your plugin:

```ts title="plugins/chat/src/ws/chat.channel.ts"
import { createWebSocketChannel } from "@vitnode/core/ws/types"

export interface MessagePayload {
  roomId: string
  message: string
  senderId: number
}

// [!code ++:5]
export const chatChannel = createWebSocketChannel<never, MessagePayload>({
  pluginId: "@acme/chat",
  module: "rooms",
  id: "messages",
})
```

The first type parameter is what the client sends, the second what it receives.
The channel id becomes `{pluginId}_{module}_{id}`.

---

## Client-Side Consumption [#client-side-consumption]

Listen for incoming channel messages with `useVitNodeWebSocket`:

```tsx title="plugins/chat/src/views/chat-room.tsx"
import { useVitNodeWebSocket } from "@vitnode/core/ws/use-websocket"
import { chatChannel } from "../ws/chat.channel"

export const ChatRoom = ({ roomId }: { roomId: string }) => {
  const [messages, setMessages] = React.useState<string[]>([])

// [!code ++:7]
  useVitNodeWebSocket(chatChannel, {
    onMessage: (payload) => {
      if (payload.roomId === roomId) {
        setMessages((prev) => [...prev, payload.message])
      }
    },
  })

return (
    <div>
      {messages.map((msg, i) => (
        <p key={i}>{msg}</p>
      ))}
    </div>
  )
}
```

---

## Rooms [#rooms]

A room is a named group of browser tabs, such as everyone looking at one chat thread or editing one record. Send a message to a room and only its members get it, on every API instance. A room is any string your feature picks, for example `chat:42`.

### Join and leave per tab [#join-and-leave-per-tab]

All tabs of a browser share one socket, so a socket joins a room on behalf of a tab. Let each tab send its own random `clientId` with every message, and join or leave with it:

```ts title="plugins/chat/src/api/modules/rooms/rooms.socket.ts"
import { buildWebSocket } from "@vitnode/core/api/lib/websocket"
import { wsRegistry } from "@vitnode/core/ws/registry"

interface RoomMessage {
  clientId: string
  roomId: string
  type: "join" | "leave"
}

export const roomsSocket = buildWebSocket<RoomMessage>({
  id: "presence",
  onMessage: ({ data, ws }) => {
    const room = `chat:${data.roomId}`

// [!code ++:5]
    if (data.type === "join") {
      wsRegistry.join(ws, room, data.clientId)
    } else {
      wsRegistry.leave(ws, room, data.clientId)
    }
  },
})
```

Register the socket on its module with `webSockets: [roomsSocket]`. The socket stays in the room until its last tab leaves, so a closed tab never cuts off the others. Check who may join (the session on `c`, a permission) before calling `join`: a room is only as private as that check.

`join` and `leave` return `true` when they changed something. `wsRegistry.membersOf(room)` lists the members on this instance and `wsRegistry.roomsOf(ws)` lists the rooms of one socket.

### Send to a room [#send-to-a-room]

```ts
// [!code ++:4]
c.get("realtime").toRoom(`chat:${roomId}`, chatChannel, {
  roomId,
  message: "Hello!",
  senderId: user.id,
})
```

Each socket in the room receives the payload once, however many of its tabs joined. Put the room or record in the payload so every tab can ignore what is not its own.

### Clean up when a socket closes [#clean-up-when-a-socket-closes]

A socket that closes leaves all of its rooms. Use `onConnectionClose` to update your own state, such as an "online now" list:

```ts title="plugins/chat/src/api/modules/rooms/presence.ts"
import { wsRegistry } from "@vitnode/core/ws/registry"

// [!code ++:5]
wsRegistry.onConnectionClose((ws, left) => {
  for (const { memberId, room } of left) {
    markOffline(room, memberId)
  }
})
```

`left` holds every `{ memberId, room }` the socket was in. Register the listener once, at module load.

### Rooms on several instances [#rooms-on-several-instances]

With `REDIS_URL` set, `toRoom` also publishes the message over Redis, and every other instance delivers it to its own members. Room membership itself stays local to each instance.

When an instance keeps per-room state in memory, it can follow the other instances:

- `onRemoteRoomMessage((room, id, data) => ...)` sees room messages from other instances before they reach local sockets. A collaborative document uses it to apply the same edit to its own copy.
- `publishToInstances(topic, data)` and `onInstanceMessage(({ topic, data, origin }) => ...)` exchange data between instances that never reaches a socket, such as each instance's list of members. Republish it periodically and let entries from a silent instance expire, so a crashed instance leaves no ghosts.

Without Redis, all of this works on a single instance with no extra setup: `toRoom` delivers locally and instance messages go nowhere.

---

## Architectural Highlights [#architectural-highlights]

- **Single Connection**: Only one `/api/ws` socket is opened per client. All features share it via message multiplexing.
- **Tab Leader Election**: When a user opens multiple tabs, a Web Lock elects one leader tab to hold the socket, distributing messages across tabs via `BroadcastChannel`.
- **Automatic Reconnect**: Backoff retry automatically re-establishes dropped connections within seconds.
- **Multiple Instances**: With `REDIS_URL` set, `sendToUser`, `broadcast` and `toRoom` are relayed to every API instance over Redis pub/sub. Without Redis they only reach clients connected to the same instance.

## Learn More [#learn-more]

# Widget Variants (/docs/dev/widgets/block-variants)

Sooner or later somebody asks for "the same callout, but smaller". You have three options: a second widget type, a `size` field in the middle of the copy, or a **variant**.

Variants are the third one, and they exist because the first two both lie about what changed. The words did not change. The shape did.

```text
data     what the widget says          "Ships on Friday"
variant  how this instance says it     "grid" | "list" | "compact"
layout   how widgets sit together      an Area's job, not a widget's
```

Keep those three apart and every screen that touches a widget stays honest. Mix them and a widget definition slowly turns into a settings page.

{/* Image prompt: Three side-by-side cards showing the same three feature items rendered three ways - as a 3-column grid of cards, as a stacked list with one item per row, and as a dense two-line summary. Above them a single shared data panel with the words "Data (one copy)" connected by three arrows to the three renderings, each labelled grid, list and compact. Clean dark UI, blue accents, 1600x900. */}

## Declaring them [#declaring-them]

Two optional keys on `defineWidget`:

```tsx title="plugins/example/src/widgets/features.tsx"
export const featuresWidget = defineWidget({
  component: Features,
  defaultVariant: 'grid',
  fields: featuresFields,
  id: 'features',
  name: 'Features',
  variants: [
    { id: 'grid', label: 'Grid', description: 'Cards side by side.' },
    { id: 'list', label: 'List', description: 'One per row.' },
    { id: 'compact', label: 'Compact', description: 'A dense summary.' },
  ],
})
```

| Key              | Rule                                                                                                                                                                          |
| :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `variants`       | A list of `{ id, label?, description? }`. Leave it off entirely if the widget has one look - `variants: []` is refused, because a picker of nothing is worse than no picker. |
| `defaultVariant` | Must name one of them. Setting it without `variants` is refused too.                                                                                                          |
| `id`             | Lowercase letters, digits and single hyphens, up to 32 characters. It is written into every instance that picks it, so it has to survive the round trip unchanged.            |
| `label`          | What the editor shows. Falls back to the id, so a one-word variant needs no label at all.                                                                                     |

Two variants sharing an id is refused: a stored instance names its variant by id alone, so the two could never be told apart.

## Reading it in the component [#reading-it-in-the-component]

The variant arrives as a prop, next to the data rather than inside it:

```tsx
const Features = ({ data, variant }: WidgetComponentProps<FeaturesData>) => (
  <section className={variant === 'compact' ? 'gap-2' : 'gap-4'}>
    <h2>{data.heading}</h2>
    {/* same data, three arrangements */}
  </section>
)
```

`variant` is `string | undefined`. Undefined means "nobody picked one", which is exactly when `defaultVariant` applies - so a component that wants a single answer can start with `const shape = variant ?? "grid"`.

## The stored shape [#the-stored-shape]

A variant is one more key on the instance, beside `data` and never in it:

```json
{
  "id": "01JC4Z8N9WQKX7R2M5T6V3B8HD",
  "type": "example:features",
  "variant": "list",
  "data": {
    "heading": "One block, three shapes",
    "primary": { "title": "Data" }
  }
}
```

That placement is the whole feature. Because `variant` is a sibling of `data`:

- switching it never touches, re-validates or re-saves the content,
- the block's schema stays the schema of its **content**, so a search indexer reading `data` never trips over a styling token,
- and a block that drops a variant later does not need a data migration to get rid of it.

## How a variant resolves [#how-a-variant-resolves]

```ts
import { resolveWidgetVariant } from '@vitnode/core/widgets'

resolveWidgetVariant(featuresWidget, undefined) // { kind: "resolved", variant: "grid" }
resolveWidgetVariant(featuresWidget, 'list') // { kind: "resolved", variant: "list" }
resolveWidgetVariant(featuresWidget, 'carousel') // { kind: "unknown",  variant: "carousel" }
```

An unknown variant is treated the way unreadable data is: the page shows a fallback rather than inventing a look, and the properties panel says which variant is stored and offers the ones the block does declare, so somebody can fix it in one click. Nothing is deleted on your behalf.

<Callout title="Why not just fall back to the default?">
  Because "carousel" meant something to whoever chose it. Silently rendering a
  grid would ship a page that looks fine to everybody except the person who
  asked for a carousel, and nothing anywhere would say it had been overruled. A
  visible fallback is a worse-looking page for an hour; a silent one is a wrong
  page forever.
</Callout>

## In the editor [#in-the-editor]

Select a block that declares more than one variant and a **Variant** picker sits above its fields in the properties panel.

Picking one is a single action - it updates the page immediately, marks the zone unsaved, keeps the instance's id, and leaves `data` byte for byte as it was. It is not an edit of the block's content, and the fields do not reset while you try the options.

A block with one variant, or none, shows no picker at all. There is nothing to decide.

## Backward compatibility [#backward-compatibility]

Nothing was migrated when variants landed, and nothing needs to be.

- An instance stored **before** variants existed has no `variant` key. It resolves to the block's `defaultVariant`, or to `undefined` if the block declares none - which is exactly how it rendered yesterday.
- A block that **adds** `variants` later keeps rendering every instance already stored. They simply all take the default until somebody picks something else.
- A block that **removes** a variant does not break its zone: the instances holding it are flagged as unknown and fixable, not dropped.

`variant` is optional in the stored shape, in the API's validation and in the type. A zone full of `{ id, type, data }` is a perfectly valid zone.

## When a variant is the wrong answer [#when-a-variant-is-the-wrong-answer]

| You want                                                   | Use                                                                                                 |
| :--------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| The same content in a different arrangement                | A **variant**.                                                                                      |
| Different content, or a field the other look does not have | Two **block types**. A variant that needs its own fields is two blocks wearing one coat.            |
| Blocks side by side in columns                             | An [**Area**](/docs/dev/widgets/layout-areas). Arranging _several_ blocks is never one block's job. |
| Something an editor should type                            | A **field**. If the answer is prose, a URL or a number, it is content.                              |

The smell test: if changing the option would make you want to re-word the copy, it is data. If the copy reads the same either way, it is a variant.

# The blocks() Field (/docs/dev/widgets/blocks-field)

## Adding a zone to a content type [#adding-a-zone-to-a-content-type]

```ts title="plugins/example/src/content/page.ts"
import { defineContentType, field } from '@vitnode/core/content'

export const pageContentType = defineContentType({
  id: 'example.page',
  tableName: 'example_pages',

fields: {
    title: field.text({ required: true, minLength: 3, maxLength: 200 }),
    slug: field.slug({ source: 'title' }),
    // [!code ++:4]
    content: field.blocks({
      allowed: ['core:*', 'example:callout'],
      max: 50,
    }),
  },

publication: true,
})
```

`min` and `max` count **block instances**, wherever they sit. A block inside a
[layout area](/docs/dev/widgets/layout-areas) counts towards the limit; the area
holding it does not, so an empty area counts as nothing. Two blocks are two
blocks whether they sit side by side in an area or one under the other.

A `blocks()` field is never `required` and never `nullable` - the empty list is what "no blocks" is, so a create that says nothing about the zone gets `[]`. That empty list is still checked against `min`, so a zone that declares `min: 1` refuses a create that leaves it out.

## Restricting what may go in [#restricting-what-may-go-in]

`allowed` takes three shapes, and they mix freely:

```ts
field.blocks({ allowed: '*' }) // every registered block
field.blocks({ allowed: ['core:*', 'blog:*'] }) // two whole plugins
field.blocks({ allowed: ['core:hero', 'core:text'] }) // exactly these two
```

A namespace wildcard is the useful middle: installing another plugin does not silently widen what a page may contain, while adding a block to a plugin you already trust does.

The shape is a string union on purpose, so a later `{ categories: [...] }` or `{ excluding: [...] }` object can join the array without any existing definition changing.

## The stored shape [#the-stored-shape]

One JSONB column, `NOT NULL DEFAULT '[]'`:

```sql
"content" jsonb DEFAULT '[]' NOT NULL
```

holding an ordered list of instances:

```json
[
  {
    "id": "01JC4Z8N9WQKX7R2M5T6V3B8HD",
    "type": "core:hero",
    "data": { "title": "Build your community", "align": "start" }
  },
  {
    "id": "01JC4Z8N9X3R7T2M5Q6K8V4B9F",
    "type": "example:callout",
    "data": { "title": "Heads up", "body": "...", "tone": "info" }
  }
]
```

| Key       | Rule                                                                                                                                               |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`      | Stable and unique **within the zone**. Never the array index - a reorder must not change what a block is.                                          |
| `type`    | The globally unique block id.                                                                                                                      |
| `data`    | Validated against that block's own field schema.                                                                                                   |
| `variant` | Optional. The look this instance picked, from the ones its block [declares](/docs/dev/widgets/block-variants). Absent means "the block's default". |

Array order **is** the rendered order. Nothing sorts it.

### Areas in the same list [#areas-in-the-same-list]

A zone holds **content nodes**, and a node is either a block instance or an [Area](/docs/dev/widgets/layout-areas) - a small layout container with its own id, a `layout` of four tokens, and `children` that are blocks:

```json
{
  "id": "01JC4Z8N9X3R7T2M5Q6K8V4B9F",
  "kind": "area",
  "layout": { "columns": 2, "gap": "md" },
  "children": [
    { "id": "01JC…", "type": "core:text", "data": { "heading": "Left" } }
  ]
}
```

An Area is told apart by `kind: "area"`, needs no entry in `allowed` - its children are checked against the same list the zone's own blocks are - and cannot contain another Area. A zone stored before Areas existed is a list of blocks, which is a list of nodes that never nests, so nothing was migrated.

### Why one column [#why-one-column]

A block instance is a document: an id, a type, and whatever that type declares. Splitting it across tables would buy a join per zone, a migration per new block, and an ordering Postgres would have to rebuild on every read. One `UPDATE` re-orders a whole page, and a revision snapshot of it is a value rather than a graph - which is what makes drafts, revisions and reusable blocks tractable later.

### Instance ids [#instance-ids]

`createBlockInstanceId()` produces a 26-character Crockford base32 identifier - 10 characters of millisecond timestamp, then 16 of randomness. It sorts by creation time, which is what lets a later merge of two edits order instances it has never seen.

```ts
import { createBlockInstance } from '@vitnode/core/widgets'

const hero = createBlockInstance('core:hero', { title: 'Build your community' })
// { id: "01JC4Z8N9W…", type: "core:hero", data: { title: "…" } }
```

Storage accepts any stable id of 1-64 URL-safe characters, so an imported document or a reusable block can keep the identity it arrived with.

## What the API checks on a write [#what-the-api-checks-on-a-write]

Every create and update runs the zone through the registry, once, before anything is stored - so a row that exists has already been validated. Nothing re-checks it on read, and [the renderer never repeats that schema parse](/docs/dev/widgets/rendering#validation) - it only compares the stored shape against the block's current fields, so a definition that moved on since the write cannot reach a component.

The whole request is refused if any instance fails:

Errors are keyed by the instance's index, so a client can point at the block that is wrong.

## Localization [#localization]

```ts
content: field.blocks({ localized: true })
```

The column moves to the generated translation table, exactly as a localized `text` field does, and keeps the translation lifecycle, revisions and preview it already had - no new concepts.

What this localizes is the **whole block document**, not the text inside each block. Each language owns its own list: which blocks are in it, what is in them, and what order they come in. The two need not correspond at all.

```text
en:  core:hero  →  core:text  →  core:cta
pl:  core:hero  →  core:cta   →  blog:gallery
```

That is deliberate. A translated landing page is rarely the same page with different words - a market may need a different call to action, or no gallery - and treating a zone as one translatable document is what makes that expressible. It is also the only model that reuses VitNode's existing localization: a per-field locale map inside JSON would be a second localization system that the translation table, the revision history and the public locale resolution all know nothing about.

The cost is the other side of the same coin: adding a block to one language does not add it to the others, and there is no "this paragraph is the translation of that paragraph" link between two locales. A field inside a block is therefore never `localized: true`; see [Defining a block](/docs/dev/widgets/defining-a-block#localization).

## Editing one [#editing-one]

A `blocks()` field is the storage half, and the [Visual Editor](/docs/dev/widgets/visual-editor) is how somebody arranges what goes in it. The two are joined by whatever your page hands the editor and whatever your API does with the payload that comes back - the field's own `allowed`, `min` and `max` are re-checked on the way in either way.

For a zone that is not a column on a record at all - a settings screen, a forum index, anything a page simply _has_ - the storage half is core's, and you declare the zone rather than a field. See [Editable Pages](/docs/dev/widgets/editable-pages).

## Exposing the zone publicly [#exposing-the-zone-publicly]

`blocks` is publicly exposable, and crosses whole:

```ts
publicApi: {
  path: "pages",
  fields: ["title", "slug", "content", "publishedAt"],
}
```

The public read returns the instances in stored order, each one's `data` already validated on the way in.

## What a zone is not [#what-a-zone-is-not]

|                                 |                                                                                                                                                                            |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Not indexable**               | A btree index over a JSONB document orders pages by their serialised bytes. `indexes` refuses it.                                                                          |
| **Not filterable or orderable** | For the same reason.                                                                                                                                                       |
| **Not searchable**              | Indexing block prose into search is its own stage.                                                                                                                         |
| **Not an AdminCP form field**   | The generated form and the DataTable both leave it out - a zone is arranged on the page by the [Visual Editor](/docs/dev/widgets/visual-editor), not typed into a control. |

# Content Zones (/docs/dev/widgets/content-zones)

A **Content Zone** is a place on a page where widgets may appear, named by the developer who put it there.

```tsx title="src/routes/_main/pages.$slug.tsx"
import { ContentZone } from '@vitnode/core/widgets/zone'

import { blocksRegistry } from '@/blocks.gen'

;<ContentZone id="main" blocks={page.content} registry={blocksRegistry} />
```

That is the whole idea. A zone takes a list of block instances and renders them through [`ContentRenderer`](/docs/dev/widgets/rendering). What it adds on top is a **name** - and a name is what the [Visual Editor](/docs/dev/widgets/visual-editor) and [Editable Pages](/docs/dev/widgets/editable-pages) use to place, rearrange, and save widgets on the page.

```text
Public page
   ↓
ContentZone
   ↓
ContentRenderer
   ↓
Blocks
```

## A zone id is not a block id [#a-zone-id-is-not-a-block-id]

These two identifiers are easy to confuse and never interchangeable.

A page has a handful of zones and they do not change when content does. A zone holds any number of block instances, and which ones it holds changes every time somebody edits the page.

### Rules for a zone id [#rules-for-a-zone-id]

One or more `:`-separated segments of lowercase letters, digits and single hyphens, up to 64 characters.

```tsx
<ContentZone id="main" />
<ContentZone id="sidebar" />
<ContentZone id="before-profile" />
<ContentZone id="homepage:hero" />
<ContentZone id="settings:before-profile" />
```

The optional prefix is yours to use however you like - a screen, a plugin, a section. `settings:before-profile` and `profile:before-profile` are two different zones, which is the point.

A zone id is never generated and never an array index. Saved editor state will address zones by these strings, so an id that changes is a zone that loses its content. `ContentZone` refuses anything it could not address later:

```tsx
<ContentZone id="Before Profile" blocks={content} />
// BlockError: Content zone id "Before Profile" is not usable. …
```

That throws the first time the page renders, in development or in a test, because a zone id is a literal you wrote - never something a visitor can influence.

### One id, one place on the page [#one-id-one-place-on-the-page]

A zone id names a **location**, so two zones on one page may not share one. Render the same id twice and view mode simply renders both lists, but edit mode refuses:

```tsx
<ContentZone id="main" />
<ProfileForm />
<ContentZone id="main" />
// BlockError: Two `<ContentZone id="main" />` outlets are on the page at the same time…
```

The editor stores, moves and saves blocks by zone id. With two of them it cannot tell which place a block belongs to, and a save would write one over the other - so it says so the moment both are on the page, rather than picking one and being wrong quietly. Moving a zone to a different element, re-rendering it under another branch of the page, and React's double-invoked effects in development are all fine: the refusal is only for two elements that are genuinely on the page at once.

Need the same content in two places? Two ids - `main` and `main-aside` - and the page decides what goes in each.

## Zones around locked application UI [#zones-around-locked-application-ui]

This is the case Content Zones exist for. Not every page is a CMS page: most of an application is code, and the useful thing is to be able to put content _around_ it.

```tsx title="src/routes/_main/settings.tsx"
<UserSettingsLayout>
  <ContentZone
    id="settings:before-profile"
    blocks={layoutContent.beforeProfile}
  />

<ContentZone
    id="settings:after-profile"
    blocks={layoutContent.afterProfile}
  />
</UserSettingsLayout>
```

`ProfileForm` is application code. It has validation, permissions and tests, and nobody is going to drag a block into the middle of it. The two zones around it are content widgets - an authorized moderator clicks **Edit widgets** in the user menu to rearrange them without touching the form.

```text
editable zone
   ↓
locked system UI
   ↓
editable zone
```

<Callout title="See it running">
  `/example/zones` in the example plugin is exactly this page: four zones around
  a profile form that stays application code.
</Callout>

## Several zones on one page [#several-zones-on-one-page]

Nothing assumes one zone per page. Each one has its own id, its own list and its own rules.

```tsx
<>
  <ContentZone id="hero" blocks={page.hero} />

<ContentZone id="after-content" blocks={page.afterContent} />
</>
```

## What a zone renders [#what-a-zone-renders]

By default: **nothing but the blocks**. No wrapper, no element, no class.

That is deliberate. A zone often lives inside a flex or grid container, and an uninvited `<div>` there is a broken `gap` and a column that stopped being a column.

Ask for a wrapper when you want one:

```tsx
<ContentZone
  as="aside"
  className="flex w-full flex-col gap-4 md:w-64"
  id="settings:sidebar"
  blocks={content}
/>
```

`as` takes an **HTML element name** - `"section"`, `"aside"`, `"header"`, `"ul"` - and not a component. The wrapper's job is to carry the zone's identity into the DOM, and a component is free to drop the `data-*` props it is handed, which would lose that identity silently and only in the case nobody tests. If you want the zone inside a component of yours, compose instead of substituting:

```tsx
<Card>
  <ContentZone id="settings:sidebar" blocks={content} />
</Card>
```

That reads better anyway, and the zone stays exactly as heavy as it was.

## Empty zones [#empty-zones]

An empty zone renders **nothing at all** - wrapper included.

```tsx
<ContentZone id="sidebar" blocks={[]} />
```

There is no empty container, no stray border and no gap in a flex column. `null`, `undefined` and `[]` behave identically, so a page whose zones are all empty is byte-for-byte a page without zones. The registry is not even consulted.

This is a deliberate performance and layout decision, not an oversight. Most zones in an application are empty most of the time - a page with eight placement points and two filled ones should cost exactly two. Emitting a marker element for the other six would put six nodes in every visitor's document, participate in every flex and grid calculation, and exist for the benefit of a person who is not there.

An editor will need to _see_ an empty zone in order to drop something into it. That is edit mode's job, and edit mode can render whatever placeholder it likes, because by then somebody has asked for it.

## Restricting what may go in a zone [#restricting-what-may-go-in-a-zone]

`allowedBlocks` takes the same shape - and means the same thing - as `allowed` on a [`blocks()` field](/docs/dev/widgets/blocks-field#restricting-what-may-go-in):

```tsx
<ContentZone
  id="main"
  blocks={page.content}
  allowedBlocks={['core:*', 'blog:*']}
/>
```

There is one allowlist format in VitNode, one function that evaluates it, and this is it.

### Two allowlists, two jobs [#two-allowlists-two-jobs]

The same value means two different things in two places, and the difference matters.

|                | `field.blocks({ allowed })` | `<ContentZone allowedBlocks>`               |
| :------------- | :-------------------------- | :------------------------------------------ |
| **Is**         | a write boundary            | a description of the location               |
| **Runs**       | on every create and update  | not at all in production                    |
| **On refusal** | the whole request is a 422  | the block is skipped in development         |
| **Answers**    | "may this be stored?"       | "what belongs here?"                        |
| **For**        | the API                     | the future editor, and you reading the page |

The field is the thing that _enforces_. A stored instance has already crossed it, so a page re-checking the same list on every render would be paying twice for one answer. The zone's copy exists to say what a location is for - which is what a block picker will need, and what a reader of the JSX needs.

Public rendering is therefore **not** a second _schema_ validation boundary - it re-parses nothing, though it does always check that a stored block still structurally matches its block's fields. What the zone does with its allowlist follows the same `validate` modes the [renderer](/docs/dev/widgets/rendering#validation) already uses, and it _skips_, never rejects:

In development the block is skipped, a dashed notice names it, and one `console.warn` is logged per block type - a development aid for content that drifted, not a gate. In production the write boundary is trusted and nothing is checked at all.

`validate="always"` is the exception, for a page rendering blocks the API never saw - a live import, a third-party feed. Even then it costs one `Map` lookup and a list scan per block, not a schema parse.

### Declaring the allowlist once [#declaring-the-allowlist-once]

The zone's allowlist and the field's `allowed` are usually the same value, and writing it twice is a typo waiting to happen.

If the page is an [editable page](/docs/dev/widgets/editable-pages), do not write it on the page at all. `defineEditablePage` declares each zone's allowlist once, and `<EditablePage>` hands every zone under it both the allowlist and the blocks:

```tsx title="plugins/example/src/pages/zones-page.tsx"
<EditablePage layout={layout} page={settingsPage}>
  <ContentZone id="before-profile" registry={blocksRegistry} />
</EditablePage>
```

An `id` is the whole zone. There is no second copy to drift, and asking for a zone the page does not declare throws rather than rendering one no save will ever reach.

You may still pass props on a declared zone, with one rule: the page declaration is the ceiling.

|                 |                                                                                                                                                                                                                 |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blocks`        | Overrides where the content comes from - the array you pass is what renders.                                                                                                                                    |
| `allowedBlocks` | **Narrows only.** It is intersected with the page's allowlist, so `"*"` here cannot re-open a zone the page restricted, and an intersection of nothing is a developer error rather than a zone nobody can fill. |
| `min` / `max`   | **Tighten only.** The higher `min` and the lower `max` win, and a `min` that ends up above the `max` throws where you wrote it.                                                                                 |

That is only true for a zone an [editable page](/docs/dev/widgets/editable-pages#what-a-call-site-may-still-say) declares, because that declaration is what the save route checks against. A standalone `<ContentZone>` has nothing to be intersected with, so its own props are simply its own.

For a zone outside an editable page, put the array in a module of its own and import it from both ends:

```ts title="plugins/example/src/content/page-blocks.ts"
export const PAGE_BLOCKS_ALLOWED = ['core:*', 'example:callout'] as const
```

```ts title="plugins/example/src/content/page.ts"
content: field.blocks({ allowed: PAGE_BLOCKS_ALLOWED, max: 50 })
```

```tsx
<ContentZone
  id="settings:before-profile"
  allowedBlocks={PAGE_BLOCKS_ALLOWED}
  blocks={content}
/>
```

One declaration, two readers, and the page imports an array rather than a content type.

<Callout title="Why the zone does not take the field itself" type="warn">
  An earlier draft of this API accepted `field={pageContentType.fields.content}` so the allowlist could be read straight off the descriptor. It was measured and removed.

A content type is authored by _calling_ `defineContentType` at module scope, so importing one retains everything that call reaches - the field factories, the schema builders, Zod, the admin labels. On `/example/zones` the difference was **8 chunks and 23.5 kB** against **15 chunks and 181.8 kB**, to read one array of strings.

A boundary test keeps that honest: `blocks/zone.tsx` reaches `react` and nothing else, `content/define.ts` reaches Zod, and `content/fields.ts` reaches nothing - the descriptors are cheap, the content _type_ is not.

</Callout>

### Where the registry comes in [#where-the-registry-comes-in]

Pass it, from the route that renders blocks:

```tsx
import { blocksRegistry } from '@/blocks.gen'
```

`blocks.gen.ts` statically imports every configured plugin's block components, so importing it from a root module - `router.tsx`, a root layout - would put every block in the application on every page, including the ones that render none. Import it in the route that needs it and it stays in that route's chunk. A test asserts the application's root router cannot reach it.

A plugin cannot see the host's generated file at all, so a plugin-owned page builds the registry it needs from the blocks it knows about:

```tsx title="plugins/example/src/pages/zones-page.tsx"
import { createBlockRegistry } from '@vitnode/core/widgets'
import { blocks as coreBlocks } from '@vitnode/core/widgets/built-in'

import { blocks as exampleBlocks } from '@/blocks'

const blocksRegistry = createBlockRegistry([coreBlocks, exampleBlocks])
```

Either way the registry is a value the page owns, and nothing global had to be set up first.

## A zone never fetches [#a-zone-never-fetches]

`ContentZone` is rendering infrastructure. It takes block data as a prop and never goes looking for it.

```text
route loader
   ↓
one request for the page
   ↓
zones render what it returned
```

The alternative writes itself, and it is the thing to avoid:

```text
page
  ├ zone A → request
  ├ zone B → request
  └ zone C → request
```

Five zones on a settings page would be five round trips for data that came from one row. A block that genuinely needs its own data - "the six newest articles" - fetches it inside its own component, where it can be cached and suspended on its own terms.

## Performance [#performance]

A zone costs a function call.

- **No request.** It renders the list it was given.
- **No hydration.** It holds no state, subscribes to nothing, and server-renders like any other component. A page full of zones ships the same JavaScript as a page without them.
- **No editor.** `@vitnode/core/widgets/zone` reaches React and `ContentRenderer`, and that is the entire list. A boundary test asserts the reachable module graph, so drag-and-drop, forms, query and AdminCP code cannot drift into it later.
- **No DOM.** Unless you ask for a wrapper, a zone is not in the markup at all.

## What the editor will find [#what-the-editor-will-find]

When a zone renders a wrapper, the wrapper carries its identity:

```html
<aside
  class="…"
  data-vitnode-zone="settings:sidebar"
  data-vitnode-zone-allowed="core:*,example:callout"
></aside>
```

Two attributes, both short strings. That is the whole metadata story for now, and it is free: they ride on an element you asked for anyway. There is no zone registry, no context and no module-level state holding a list of zones - a public page has nobody to tell.

The format stays small and predictable on purpose. An id, and a comma-separated allowlist. Nothing here will ever grow into a serialised JSON blob in an attribute: anything bigger than a couple of identifiers belongs in edit mode, where it can be a JavaScript value instead of a string somebody has to parse back out of the document.

<Callout title="A zone without a wrapper has no marker - by design" type="warn">
  Most zones render no element, so most zones leave no trace in view-mode HTML. That is the [empty-zone and no-wrapper behaviour](#what-a-zone-renders) working as intended, and it means **the set of zones on a page is not discoverable by scanning public DOM**.

Edit mode does not try. It knows its zones because it rendered them - each `ContentZone` registers itself while edit mode is on - rather than walking the document looking for attributes that were never promised to be there. That registration is also what notices [two zones claiming one id](#one-id-one-place-on-the-page): the list the editor keeps is the truth, not the DOM.

</Callout>

If you need those values yourself, `@vitnode/core/widgets` exports the pieces without any React:

```ts
import {
  assertContentZoneId,
  contentZoneAttributes,
  isContentZoneId,
  parseContentZoneId,
} from '@vitnode/core/widgets'

parseContentZoneId('settings:before-profile')
// { name: "before-profile", scope: "settings" }
```

## Props [#props]

Everything but `id` and `blocks` is optional and named, so later additions - a label, a maximum, a permission - are additions rather than a new signature.

## Verifying it yourself [#verifying-it-yourself]

`/example/zones` in the example plugin is the manual test page for everything above. It renders four zones around a locked profile form, and its own copy lists what each one should look like.

### In development [#in-development]

Start the development environment from the repository root:

```bash
pnpm dev
```

</Step>
<Step>

Open [http://localhost:3000/example/zones](http://localhost:3000/example/zones) and check the page itself:

</Step>
<Step>

Open DevTools → Elements and check the DOM:

</Step>
<Step>

Open DevTools → Network, filter to Fetch/XHR, and reload. `ContentZone` issues **no request of its own**: the blocks arrived with the route's loader data.

</Step>
<Step>

Break a zone id on purpose, to confirm it fails loudly rather than silently:

```tsx
<ContentZone id="Settings Sidebar" blocks={loaderData.sidebar} />
```

The page should throw a `BlockError` naming the id and the rule. Put it back.

</Step>
<Step>

Open an unrelated route - `/`, or `/docs` - with the Network panel open, and confirm **no block module loads**. A page that renders no blocks should never request one. This is the property the root router must not break; the [import-graph test](#performance) is the standing guard, and this is how you see it.

</Step>
</Steps>

### A block whose plugin is gone [#a-block-whose-plugin-is-gone]

Content outlives plugins, so the interesting case is a page referencing a block nothing registers. Simulate it **temporarily** - do not commit the change.

In `plugins/example/src/blocks.tsx`, comment the callout out of the registered list:

```ts
export const blocks = {
  pluginId: CONFIG_PLUGIN.pluginId,
  blocks: [], // was [calloutBlock]
} satisfies BlockPluginSource
```

The loader in `zones-page.tsx` still places an `example:callout`, which is exactly the situation: stored content naming a block that is no longer installed.

</Step>
<Step>

**In development**, reload `/example/zones`. Expect a dashed notice reading _Block "example:callout" is not registered_, one `console.warn` in the terminal and browser console, and **every other block still rendering** - the text block, the profile form, the CTA, the sidebar.

</Step>
<Step>

**In production**, run the production flow below with the same edit in place. Expect the callout to be silently absent, no notice, no error, and a 200 response. A visitor sees a page with one section missing, not a stack trace.

</Step>
<Step>

Revert `blocks.tsx`.

</Step>
</Steps>

### Against a production build [#against-a-production-build]

Dev-mode checks miss bundling, minification and real SSR, so repeat the important ones against a build:

Build and start:

```bash
pnpm build
pnpm start
```

`pnpm build` runs `vite build` for the web app; `pnpm start` serves `.output/server/index.mjs`. To do just the web app, use `pnpm --filter web build` and `pnpm --filter web start`.

</Step>
<Step>

Read the **server-rendered markup**, not the hydrated DOM - `view-source:`, or:

```bash
curl -s http://localhost:3000/example/zones | grep -o 'data-vitnode-zone[^>]*'
```

Exactly one match, for the sidebar. The unwrapped zones contribute no attribute, and the empty one contributes nothing.

</Step>
<Step>

Confirm the block content is in the HTML the server sent, not painted in afterwards - search the source for a block's text. If it is there, the zone server-rendered and needs no hydration to be readable.

</Step>
<Step>

Confirm no editor code reached the page:

```bash
curl -s http://localhost:3000/example/zones | grep -cE 'dnd-kit|tiptap|cmdk'
```

`0`. The [import-graph tests](#performance) are the standing guarantee; this is the spot check that the guarantee survived bundling.

</Step>
<Step>

Load an unrelated route and confirm its chunks hold no block components - search the modules it preloads for a block id such as `core:hero`:

```bash
curl -s http://localhost:3000/ | grep -o '/assets/[^"]*\.js' | sort -u
```

Fetch those and grep for `core:hero`. Nothing should match: a page that renders no blocks must not carry any.

</Step>
</Steps>

## The same zone, in edit mode [#the-same-zone-in-edit-mode]

A zone renders blocks. It is also the surface an authorized editor arranges them on - see [Visual Edit Mode](/docs/dev/widgets/visual-editor).

```text
ContentZone in view mode:
render blocks

ContentZone in edit mode:
render blocks + the editing surface
```

The part worth saying is what did **not** change. Zones are still addressed by the ids you wrote, block instances by the ids already stored, and the allowlist by the format both the field and the zone already speak. Edit mode is a change inside `ContentZone`, not a change to the pages that use it - so there is no `EditableContentZone` to migrate to, and nothing stored before it existed needed rewriting.

The editor is not in the bundle of a page nobody is editing. It arrives on the first click of **Edit widgets**, through a dynamic import that a [boundary test](/docs/dev/widgets/visual-editor#the-lazy-loading-guarantee) keeps honest.

# Defining a Widget (/docs/dev/widgets/defining-a-block)

## One call [#one-call]

```tsx title="plugins/example/src/widgets/callout.tsx"
import type { WidgetComponentProps, WidgetData } from '@vitnode/core/widgets'

import { defineWidget } from '@vitnode/core/widgets'
import { field } from '@vitnode/core/content'
import { InfoIcon } from 'lucide-react'

const calloutFields = {
  body: field.textarea({ required: true, minLength: 1, maxLength: 600 }),
  title: field.text({ required: true, minLength: 1, maxLength: 120 }),
  tone: field.enum({
    defaultValue: 'info',
    values: ['info', 'success', 'warning'],
  }),
}

type CalloutData = WidgetData<typeof calloutFields>

const Callout = ({ data }: WidgetComponentProps<CalloutData>) => (
  <aside>
    <h2>{data.title}</h2>
    <p>{data.body}</p>
  </aside>
)

export const calloutWidget = defineWidget({
  component: Callout,
  description: 'A short highlighted note in one of three tones.',
  fields: calloutFields,
  icon: InfoIcon,
  id: 'callout',
  name: 'Callout',
})
```

`WidgetData<typeof calloutFields>` is the inferred data type: `title` and `body` are `string`, `tone` is `"info" | "success" | "warning" | undefined` because it has a default. Nothing is written twice.

## Give it an icon [#give-it-an-icon]

`icon` is the picture people see next to the widget's name in the [Visual Editor](/docs/dev/widgets/visual-editor): on its card in the catalogue, on the card that follows the pointer while it is dragged, and at the top of its properties panel. Pass the icon **component**, not an element - `icon: InfoIcon`, not `icon: <InfoIcon />` - so the editor can size and colour it to match everything around it.

```tsx
import { MegaphoneIcon } from 'lucide-react'

export const promoWidget = defineWidget({
  component: Promo,
  fields: promoFields,
  icon: MegaphoneIcon,
  id: 'promo',
})
```

Any component that accepts a `className` works, so an icon from another set or your own inline SVG is fine too. Pick one that says what the widget **is** at a glance: a megaphone for a call to action, a "T" for text. Leave `icon` off and the widget gets the generic widget icon, which is fine but makes every such card look alike. Core's own widgets use `PanelTopIcon` (Hero), `MegaphoneIcon` (Call to action) and `TypeIcon` (Text).

The icon only shows up in the editor. Your widget's component on the public page never renders it.

## Component props [#component-props]

```ts
interface WidgetComponentProps<TData> {
  /** The instance's own stable id - not the widget's. */
  widgetId: string
  data: TData
  index: number
  type: string
  variant?: string
}
```

`data` has already been through the widget's schema when the component runs, so a component never checks for missing fields. `variant` is the look this instance picked, and is `undefined` for a widget that offers none.

<Callout type="warn" title="A text field is not a safe link">
  The schema checks that a `field.text()` is a string, not that it is a URL you want people clicking. If your widget turns one into an `href`, check it with `isValidNavigationHref` from `@vitnode/core/lib/navigation` first - it allows a site path (`/discover`) or an `https://` URL and refuses `javascript:` and friends. Core's Hero and Call to action widgets simply leave the link out when it fails.
</Callout>

## Two looks, one widget [#two-looks-one-widget]

A widget that should render the same content in more than one shape declares its shapes instead of growing a `style` field:

```tsx
export const featuresWidget = defineWidget({
  component: Features,
  defaultVariant: 'grid',
  fields: featuresFields,
  id: 'features',
  variants: [{ id: 'grid' }, { id: 'list' }, { id: 'compact' }],
})
```

The chosen variant is stored **beside** the instance's data, never inside it, and the editor grows a picker for it with no further work. See [Block Variants](/docs/dev/widgets/block-variants) for the resolution rules and what happens to a stored variant a block stops offering.

## Ids are namespaced for you [#ids-are-namespaced-for-you]

Write `id: "callout"`. The registry prefixes the namespace of the plugin that registered it, derived from the **last segment** of the package name:

Writing the namespace yourself is an error - a block would otherwise be addressable under two names, and content written under the wrong one would be unrenderable.

Two packages whose names end in the same segment (`@vitnode/blog` and `@acme/blog`) collide. The registry refuses to build and names both; set `namespace` on one of their `blocks` modules to settle it.

## Which fields a block may hold [#which-fields-a-block-may-hold]

Every one of those rules lives in one table, `blockFieldKindRefusal`, and the error a refused field produces quotes the reason from it.

<Callout title="Media and relations are a limitation of today, not of the model">
  The serialized shape - `{ id, type, data }`, with `data` holding this field map's values - does not change when these land: a `file` field would store a `core_files.id` exactly as a file *column* does. What is missing is the lifecycle around it. A content column pins its file with `ON DELETE RESTRICT`, which is what makes the Files screen answer 409 instead of leaving a published page pointing at bytes that are gone; a value inside JSONB has no foreign key to carry that.

The intended solution is to extract a widget's references out of its data on write - the field map already says which leaves are references - and pin them in a reference table the same way, so deletion, cleanup and `onDelete` keep working. Until that exists, storing a bare id in JSON would be a foreign key with none of the guarantees of one, which is worse than not supporting it. Put the image on the record for now and let the widget choose how to present it.

</Callout>

## Localization [#localization]

A widget's **fields** are never `localized: true`. There is no translation row for them to live in, and per-field locale maps inside JSON would be a second localization system that revisions, preview and the public locale resolution know nothing about.

The **zone** is what translates:

```ts
content: field.widgets({ localized: true })
```

This is document-level localization, not translated field values: each language gets its own widgets, in its own order, and the two need not correspond at all.

```text
en:  Hero  →  Text  →  CTA
pl:  Hero  →  CTA   →  Gallery
```

See [The blocks() field](/docs/dev/widgets/blocks-field#localization).

Editing a widget's text in the [properties panel](/docs/dev/widgets/visual-editor#the-properties-panel) changes nothing about this. What somebody types goes into the `data` of the snapshot the page mounted for the locale it is showing, and it is saved by whoever already owned that locale's zone.

## Validating data by hand [#validating-data-by-hand]

A definition is metadata: an id, the field map and the component. It carries no schema of its own, which is what keeps `defineWidget` - and therefore every public page that renders a widget - free of a validation library. The schema is derived from the fields on demand:

```ts
import { parseWidgetData, widgetDataSchema } from '@vitnode/core/widgets'

const data = parseWidgetData(calloutWidget, { title: 'Heads up', body: '...' })
// { title: "Heads up", body: "...", tone: "info" }

widgetDataSchema(calloutWidget).safeParse(input)
```

`parseWidgetData` applies defaults and throws a `BlockError` naming the field when the value does not fit; its return type is inferred from the definition's field map. `widgetDataSchema` is the underlying Zod object, built once per definition and cached.

A variant is not part of that schema, and neither is the arrangement of the widgets around this one - those are the instance's `variant` and its [Area's layout](/docs/dev/widgets/layout-areas). The rule of thumb: **`data` is what the widget says, `variant` is how this instance says it, `Area.layout` is how widgets sit together.**

The Content Engine calls these for you on every write. You need them only when you are producing widget data outside the API - a seed, a migration, an importer.

# Editable Pages (/docs/dev/widgets/editable-pages)

A settings page is edited on the settings page. A forum index is edited on the forum index. Nobody opens an admin screen to arrange a page they cannot see.

```text
the real page
   ↓  Edit widgets        ← in the user menu, only if you hold the page's permission
the same page, editable
   ↓  Save
   ↓  Finish editing
the real page again
```

That is the whole feature. What you write to get it is one page declaration, one line of registration, and `<EditablePage>` around the zones you already had. **The button is not yours to draw** - it lives in the user menu in the site header, on every page, and appears there by itself the moment an editable page somebody may edit is on screen.

{/* Image prompt: A clean left-to-right technical diagram on a dark background. Three labelled boxes joined by arrows. First: "defineEditablePage" showing a small list of zone names (before-profile, sidebar, after-profile) each with a tiny allowlist pill beside it. Second: a miniature browser window titled "/example/zones" with two dashed zone outlines around a solid form, and a small outlined button in the corner reading "Edit widgets". Third: a database icon labelled "core_page_layouts" with one row shape beside it, split into a "pageId" cell and a wider "zones JSONB" cell holding two small zone chips. A thin annotation under the middle box reads "one declaration, three readers". Blue accent on the arrows, neutral grey boxes, 1600x600. */}

## The whole thing, in three files [#the-whole-thing-in-three-files]

### 1. Declare the page [#1-declare-the-page]

```ts title="plugins/example/src/content/settings-page.ts"
import { defineEditablePage } from '@vitnode/core/content/editor'

import { PAGE_BLOCKS_ALLOWED, PAGE_SIDEBAR_BLOCKS_ALLOWED } from './page-blocks'

export const settingsPage = defineEditablePage({
  id: 'example:settings',

permission: { module: 'widgets', permission: 'can_edit' },

zones: {
    'before-profile': {
      allowed: PAGE_BLOCKS_ALLOWED,
      max: 20,
      default: [
        {
          id: '01JEXAMPLEZONESBEFORE00001',
          type: 'example:callout',
          data: {/* … */},
        },
      ],
    },
    'after-profile': { allowed: PAGE_BLOCKS_ALLOWED, max: 20 },
    sidebar: { allowed: PAGE_SIDEBAR_BLOCKS_ALLOWED, max: 20 },
    'before-footer': { allowed: PAGE_BLOCKS_ALLOWED, max: 20 },
  },
})
```

|              |          |                                                                                                                                     |
| :----------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | required | The page's stable identity, `plugin:page`. The stored layout is keyed by it, so it is written once by hand and never generated.     |
| `permission` | required | The **moderator** permission somebody needs before the editor will offer to open. `plugin` defaults to whoever registered the page. |
| `zones`      | required | One entry per place on the page blocks may go. At least one.                                                                        |

And per zone:

|               |                                                                                                                                                             |
| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed`     | The block allowlist, or `"*"`. Declared **here**, so the page never repeats it.                                                                             |
| `max` / `min` | How many **blocks** the zone accepts. An area counts nothing itself; the blocks inside it each count one. Leaving `max` out is not "unlimited" - see below. |
| `default`     | The layout the zone ships with, as real stored nodes.                                                                                                       |

#### Three limits, and they count different things [#three-limits-and-they-count-different-things]

Leave `max` out and the zone still has one: **200**, the `CONTENT_BLOCKS_DEFAULT_MAX` a [`blocks()` field](/docs/dev/widgets/blocks-field) already defaults to, because a zone and a field are stored and validated by the same code. Omitted means "the usual ceiling", never "as many as you like".

| Limit                         | Value                                          | Counts                                                                                                                                                                                                        |
| :---------------------------- | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| A zone's `max` / `min`        | `200` when `max` is omitted, `0` when `min` is | **Block instances.** A block inside an [area](/docs/dev/widgets/layout-areas) counts one; the area holding it counts nothing, so an empty area counts as nothing at all.                                      |
| `CONTENT_BLOCKS_ABSOLUTE_MAX` | `1000`                                         | **Nodes in the zone's root list** - blocks and areas alike, children not included. It is the ceiling the stored column can be read back through, so a zone's own `max` may lower it and nothing may raise it. |
| `AREA_CHILDREN_DEFAULT_MAX`   | `50`                                           | **One area's children.** A third limit, checked per area, unrelated to the two above.                                                                                                                         |

All three are exported from `@vitnode/core/widgets`, and a zone that declares a `min` above its effective `max` is refused where it is declared rather than the first time somebody saves.

Zone ids are **page-local**: `"sidebar"`, not `"settings:sidebar"`. The page id already namespaces them - it is what the stored layout is keyed by, and the zone ids are the keys inside it.

<Callout title="The defaults are content, not a placeholder">
  A zone nobody has customised renders its `default`, and the read that serves
  it says so with `updatedAt: null`. That is the layout you shipped - it is what
  a visitor sees before anybody has touched the page, and what a future *reset*
  will restore to. So it lives in code rather than being seeded into the
  database, and the first **Save** is entitled to write over it.
</Callout>

The definition module is a plain value with **no third-party import anywhere in its graph**, which is what lets the API and a public page import the same file. Ask for a zone it does not declare - on the page, in a save, anywhere - and it throws with the zone ids it does declare.

### 2. Register it [#2-register-it]

```ts title="plugins/example/src/config.api.ts"
buildApiPlugin({
  pluginId: CONFIG_PLUGIN.pluginId,
  // [!code ++:4]
  editablePages: [settingsPage],
  permissionStaff: {
    moderator: { widgets: ['can_edit'] },
  },
  modules: [adminModule /* … */],
})
```

Two lines, and both are needed for different reasons. `editablePages` is what makes the page id resolvable on the server: without it, a read is a `404` and a save is a `400`. `permissionStaff.moderator` is what puts **Widgets → can edit** in front of somebody granting it - a permission nobody can grant is a permission nobody holds.

Registering one page id twice, or two plugins claiming the same id, is a startup error rather than a race about which loaded last. So is declaring a page whose permission is missing from that plugin's `permissionStaff.moderator` catalogue: the server would boot, the page would read fine, and nobody outside a root role could ever edit it - which is a thing you want to hear at boot rather than from somebody who cannot find the button.

### 3. Render it [#3-render-it]

```tsx title="plugins/example/src/pages/zones-page.tsx"
// [!code ++:4]
<EditablePage
  adapter={adapter}
  canEdit={canEdit}
  layout={layout}
  openEditing={search.edit === true}
  page={settingsPage}
>
  <ContentZone id="before-profile" registry={blocksRegistry} />
  <ProfileForm />
  <ContentZone
    as="aside"
    className="w-full lg:w-64"
    id="sidebar"
    registry={blocksRegistry}
  />
</EditablePage>
```

`<ContentZone id="sidebar" />`. That is the entire zone. No `blocks`, because the provider holds the layout. No `allowedBlocks`, because the provider holds the allowlist. On a page that declared its zones there is nothing left to pass.

#### What a call site may still say [#what-a-call-site-may-still-say]

You can pass those props anyway, and they still do something - just not _anything_. The page declaration is what the server checks a save against, so a zone on that page can be narrowed at the call site and never widened.

| At the call site |                                                                                                                                                                                                                           |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `blocks`         | **Overrides the source.** For a zone whose content genuinely comes from somewhere else, the array you pass is what renders.                                                                                               |
| `allowedBlocks`  | **Only narrows.** It is intersected with the page's allowlist, so `"*"` here cannot open a zone the page restricted, and asking for blocks the page does not allow is a developer error rather than a quietly wider zone. |
| `min` / `max`    | **Only tighten.** The higher `min` and the lower `max` win. Ask for a combination no list of blocks could satisfy - a `min` above the `max` - and it throws where you wrote it.                                           |

The page stays the ceiling and the floor. That is what makes "the zone as declared" the one thing both the editor and the save route have to agree on, and it is why an intersection is refused rather than silently emptied: a zone allowing nothing at all is a page nobody could edit.

A **standalone** `<ContentZone>` - one no editable page declares - is unaffected. There is nothing to intersect with, so its own `allowedBlocks`, `min` and `max` are simply its own.

Edit mode itself is **not a prop**. The page that is editable and the action that opens it are in two different parts of the document - one in `<main>`, the other in the header - so neither may own the state between them. `<EditablePage>` publishes what it is and whether this visitor may edit it; the site shell holds "is somebody editing", answers the user menu with it, and reserves the sidebar's room from the whole page while it is true. Walk away from the page and the offer leaves with it, so the entry is never there for a page that has no zones.

`EditablePage` also adopts the canonical **zones** a save comes back with, so the editor rebases onto what the server actually stored. View mode shows the stored result the moment you press **Finish editing**, with no reload and no second request. The metadata around those zones - `updatedAt` and friends - belongs to the page that owns the layout, not to the editor: hold the payload the save answered with in your own state, and a "Last rearranged 2 minutes ago" line moves with it instead of sitting on the timestamp the loader happened to read. Hand `EditablePage` a layout belonging to a different page id and it throws, because rendering one page's blocks under another page's zones is how a save writes them onto the wrong page.

## Loading it [#loading-it]

```ts title="plugins/example/src/pages/zones-page.tsx"
const [stored, staff] = await Promise.all([
  fetcher({
    plugin: '@vitnode/core',
    method: 'get',
    module: 'pages',
    path: '/layout',
    args: { query: { pageId: settingsPage.id } },
  }),
  fetcher({
    plugin: '@vitnode/core',
    method: 'get',
    module: 'users',
    path: '/permissions',
  }),
])

if (!stored.ok) {
  throw new Error(`Reading this page's layout answered ${stored.status}…`)
}
```

Two public reads, one round trip. The first is the layout; the second is who is looking.

The `if` is the important line. "Nothing is stored" and "I could not read what is stored" are two different answers and must never look alike: the first is a `200` full of shipped defaults, the second is a throw. Render something plausible in place of a failed read and the next **Save** writes it over whatever the page really held.

## Saving it [#saving-it]

```tsx
const adapter = useMemo(
  () =>
    createContentEditorAdapter({
      page: settingsPage,
      save: async (payload) => {
        const response = await fetcher({
          plugin: '@vitnode/core',
          method: 'put',
          module: 'pages',
          path: '/layout',
          args: { body: payload },
        })

if (!response.ok) throw new Error(`Saving answered ${response.status}.`)

return zodLayout.parse(await response.json())
      },
    }),
  [],
)
```

The adapter turns the editor's snapshot into a payload carrying **only the zones that changed**, refuses up front to send a zone the page does not declare, and hands the server's canonical answer back so the editor rebases onto what was _stored_ rather than onto what it sent.

```ts
interface EditablePageSavePayload {
  pageId: string
  zones: Record<string, ContentNode[]> // what you want stored
  expectedZones: Record<string, ContentNode[]> // what you were editing
}
```

`expectedZones` is the second half of every save: for each zone being written, the value the editor started from. The server compares it with what is actually stored before touching anything, which is what turns "last save wins" into "the save that knew what it was replacing wins". The adapter fills it in from the editor's own baseline - you do not assemble it.

<Callout title="Two files, and neither of them the editor">
  `createContentEditorAdapter` produces a `VisualEditorAdapter`, but it needs
  nothing from the editor to do it. So it ships beside the page definition, its
  whole graph is two modules with no third-party package in it, and a plain
  `import` keeps the example plugin's boundary test green: nothing under core's
  `src/editor/` is in the page's eager graph. The `@vitnode/core/editor/adapter`
  barrel, by contrast, is thirty-three modules and Zod.
</Callout>

## The two routes [#the-two-routes]

They are core's, not your plugin's, and they are addressed by page id.

```http
GET  /api/vitnode/core/pages/layout?pageId=example:settings     public
PUT  /api/vitnode/core/pages/layout                             that page's permission
```

```ts
interface EditablePageLayoutPayload {
  pageId: string
  updatedAt: string | null // null: nothing stored, these are the defaults
  zones: Record<string, ContentNode[]>
}
```

`GET` is public, because a visitor renders the page from it. It answers with the **effective** layout - the shipped defaults with whatever has been customised laid over them - so the page renders what it is handed and resolves nothing itself. The defaults it sends have been through the same block schemas a saved zone goes through, so a zone still on its default arrives in the same shape as one somebody has edited, fields the block fills in and all. Hand `EditablePage` the layout from this route and it never has to guess: the `default` you declared is a fallback for a zone the server did not send, and it has not been through those schemas. A page id nobody registered is a `404`; a registered page nobody has rearranged is a `200` holding the declared defaults and `updatedAt: null`.

`PUT` takes `{ pageId, zones, expectedZones }` with only the zones that changed, and answers with the canonical stored value of **those zones only** - the same `EditablePageLayoutPayload`, `updatedAt` and all, which is what the page adopts so its own layout metadata stays current. The mapping from a zone id to somewhere to store it comes from the registered page, never from the body, so there is no shape of request that reaches a zone the page did not declare. A body that writes a zone without a baseline for it is a `400`: without one the server cannot tell an edit from an overwrite.

After validation the write is one read, one comparison, one merge and one upsert, whatever number of zones the save named. The block validator is the engine's own; the event - `core.page-layout.updated`, carrying the page id and the zones that changed - is emitted after the commit rather than inside it; and a save that changed nothing stores nothing, bumps no `updatedAt` and emits nothing, while still answering canonically.

### Two moderators, one page [#two-moderators-one-page]

The comparison is **per zone**, inside the same transaction that writes, which is what lets an ordinary afternoon work out:

|                                 |                                                                                                                                                                                    |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Two people, **different zones** | Both saves land. One writes the sidebar, the other the footer, and each leaves the other's zone exactly as it found it. Zones merge because a save only ever writes what it names. |
| Two people, **the same zone**   | The second one gets a `409` and **nothing is written**. The zone moved after their editor read it, so storing their copy would delete a change they never saw.                     |

A `409` is not a lost afternoon: the refusal says which zones moved, nothing that was arranged is thrown away, and reloading the page picks up what is really there to redo the change on top of it. Nothing polls and nothing locks - the baseline travels with the save, so the only thing that can ever be overwritten is a zone whose stored value is still the one being edited.

## "Can I edit this?" [#can-i-edit-this]

The page asks the existing public route:

```http
GET /api/vitnode/core/users/permissions   →   { root, permissions[] }
```

`root` is a role that holds everything and lists nothing, so it counts as yes on its own. Otherwise the page looks for its own `{ plugin, module, permission }` in the list.

<Callout title="Why a moderator permission and not an admin one" type="warn">
  An admin-type check reads `c.get("admin")`, and only `globalAdminMiddleware`
  populates it. On a public page that middleware never ran, so
  `checkStaffPermission(c, { type: "admin", … })` does not merely answer *no* - it
  answers no **structurally**, for everybody, including the person who genuinely
  administers the site. A moderator permission reads `c.get("user")`, which a public
  request does have. That is why `permission` on a page definition is a
  `permissionStaff.moderator` entry, and why `PUT /pages/layout` asserts it as one.
</Callout>

`?edit=true` may **request** edit mode - it is what a link hands you, and what `openEditing` passes on - and it never authorizes it. The page only opens in edit mode when the permission agrees, the **Edit widgets** entry is absent from the user menu otherwise, and the save asserts the permission again server-side whatever the URL said.

## Where a layout is stored [#where-a-layout-is-stored]

In core, in one ordinary table:

```ts
core_page_layouts
  pageId     varchar    primary key
  zones      jsonb      not null default '{}'
  createdAt  timestamp
  updatedAt  timestamp
```

**One row per page, holding overrides only.** `zones` is a `Record<zoneId, ContentNode[]>` carrying just the zones somebody has actually rearranged. What the page renders is the two halves put together:

```ts
effective[zoneId] = Object.hasOwn(stored.zones, zoneId)
  ? stored.zones[zoneId]
  : zone.default
```

Defaults live in code; the database stores the custom ones. A page nobody has touched has **no row at all** - which is exactly what `updatedAt: null` means. Save a zone back to precisely what it ships with and its key is dropped again; empty the object and the row goes with it. A reset is therefore a delete rather than a re-seed, and the shipped layout is written down in exactly one place.

A stored zone the page no longer declares is **ignored for rendering but not deleted**. Only declared zones are read, so nothing renders it, and no ordinary save touches it: take a zone off a page for one release, put it back in the next, and what was stored for it is still there.

None of this is a Content Engine content type. No publication, no search indexing, no generated CRUD, no AdminCP screens. Layout persistence is **internal infrastructure** - you do not browse it, any more than you browse the sessions table.

<Callout title="There is no AdminCP → Layouts screen in V1, on purpose">
  Central layout administration - listing the pages somebody has customised,
  resetting one to its shipped defaults, exporting a layout as JSON, copying one
  page's layout onto another - is deliberately left to a possible **V2**. Each
  of them is a query on one table keyed by `pageId`: list is `select "pageId"`,
  reset is a `delete`, export is a single row. The shape makes them easy later;
  none of them is built now, and none of them is needed to arrange a page.
</Callout>

Every submitted zone is re-validated against that zone's own `allowed`, `min` and `max`, read off the **registered page** rather than off the request, before anything is stored.

## When a save is refused [#when-a-save-is-refused]

Every refusal is named, and none of them falls back to a default or silently drops content.

|                                    |                                                                                                                             |
| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| A page id nobody registered        | `400`, saying there is nothing this save could be writing.                                                                  |
| A zone the page does not declare   | `400`, listing the zones it does.                                                                                           |
| No zones at all                    | `400`. A save names what it changed, and this one named none.                                                               |
| A zone written without a baseline  | `400`. Every zone in `zones` needs its counterpart in `expectedZones`.                                                      |
| A zone somebody else changed first | `409`, naming the zones that moved. Nothing is written - not even the zones that would have been fine.                      |
| A block the zone does not allow    | `400`, from the zone's own `allowed` - nested inside an area too.                                                           |
| Too many or too few blocks         | `400`, from the zone's own `max` and `min`, counting an area's children.                                                    |
| The permission is not held         | `403`.                                                                                                                      |
| The stored layout cannot be read   | `500`. A read that fails is never answered with defaults: the next **Save** would write them over whatever is really there. |

The client has its own guard before any of this: a zone holding a value the editor cannot read keeps **Save** disabled until somebody removes it deliberately. See [unreadable content](/docs/dev/widgets/visual-editor#content-the-editor-cannot-read).

## What this costs a public page [#what-this-costs-a-public-page]

The page definition is a module a public page imports, so it was measured rather than asserted. Every number is the import graph of a real file in this repository.

| Entry                                         | Source files | Third-party |
| :-------------------------------------------- | -----------: | :---------- |
| `@vitnode/core/content/editor`                |           12 | none        |
| `createContentEditorAdapter` alone            |            2 | none        |
| `EditablePage` (`blocks/page.tsx`), eagerly   |           15 | `react`     |
| `ContentZone` (`blocks/zone.tsx`)             |           19 | `react`     |
| **The example's page definition, end to end** |       **15** | **none**    |
| `@vitnode/core/content/define`                |           34 | `zod`       |
| `@vitnode/core/content` (the barrel)          |           54 | `zod`       |
| `@vitnode/core/editor/adapter` (the barrel)   |           33 | `zod`       |

A module whose whole graph has no external specifier cannot add a package to anything that imports it. That is the entire argument for keeping the declaration off the content type: a page gets its zone ids, allowlists and defaults without the schema builder that turns field descriptors into Zod.

The same rule applies to blocks. `plugins/example/src/blocks/callout.tsx` used to import `field` from `@vitnode/core/content`; switching two import paths to `@vitnode/core/content/fields` took the playground's eager graph from **132 modules to 107**, and the Content Engine modules it reaches from **41 to 16**. The rendered page was byte-for-byte identical.

```ts
import { field } from '@vitnode/core/content' // [!code --]
import { field } from '@vitnode/core/content/fields' // [!code ++]
```

Two boundary tests keep it that way. Core's own names every module `@vitnode/core/content/editor` reaches and asserts it reaches no third-party one; the example plugin's walks the **real page** and asserts nothing under core's `src/editor/` - and no drag-and-drop, command palette or database package - is in its eager graph, while following its dynamic imports does reach `@dnd-kit/core`, so the guarantee is not vacuous.

## `<PageWidgets>`: the loading, the saving and the permission, once [#pagewidgets-the-loading-the-saving-and-the-permission-once]

Everything above is the contract. You rarely write it, because core owns the two routes a layout is read and written through - so core also owns talking to them.

```tsx title="Any page that declares its zones"
import { loadPageWidgets, PageWidgets, PageWidgetsZone } from '@vitnode/core/tanstack/widgets'

export const route = defineRoute({
  load: async ({ context }) => await loadPageWidgets(context.queryClient, settingsPage),
})

const Page = () => (
  <PageWidgets page={settingsPage}>
    <PageWidgetsZone id="header" />
    <ProfileForm />
    <PageWidgetsZone id="footer" />
  </PageWidgets>
)
```

That is the whole integration. No `fetcher` call, no `createContentEditorAdapter`, no permission comparison and no registry plumbing: `PageWidgets` reads the layout and the viewer's moderator permissions, builds the adapter, folds each save's canonical answer back into the cache, and hands every `PageWidgetsZone` the right blocks and the application's block registry. It takes the page definition and nothing else - which is why the definition names its permission's `plugin` rather than leaning on the server-side default, so the browser can answer "may I edit this?" without knowing who registered the page.

`loadPageWidgets` is the one line a **route** writes. A zone never fetches and a loader is where this framework reads, so the warm belongs there - and neither query rejects, so a widget area that cannot be read costs the page it decorates nothing.

<Callout title="When to reach past it">
  Write the loader and adapter by hand when the page is not read from core's own
  layout route - zones stored on your own record, a different API, a preview of
  something unsaved. The sections above are that contract, and `<EditablePage>`
  is still what you wrap them in.
</Callout>

## Core ships one: the account settings page [#core-ships-one-the-account-settings-page]

`/settings` - the account settings screen every member of every VitNode install visits - declares two zones of its own, and is the reference for the three lines above:

Both take **every installed block**, so a plugin's own block can go there too, and both cap at ten. They ship empty: an install nobody has touched renders no extra markup at all, and the zones are invisible until somebody puts something in them.

```text
Settings                          ← the page heading
  header zone                     ← "Two-factor sign-in becomes required on 1 October."
  nav | panel                     ← application UI, not editable
  footer zone                     ← "Need a hand? Contact support"
```

Rearranging them is gated on the moderator permission `@vitnode/core` → **Widgets** → `can_edit`, grantable from **Staff → Moderators** in the AdminCP. Hold it (or a root role) and **Edit widgets** appears in the user menu while you are on `/settings`, exactly as it does on a page your own plugin declared.

<Callout>
  A zone renders from the block registry your application generated, so every plugin you configured is offered. In an install that has never rendered a block anywhere else, core's own `core:text`, `core:cta` and `core:hero` are offered instead of nothing.
</Callout>

A read failure is not fatal. If the layout route cannot be reached, the page still renders in full - just without its widget areas, and with **Edit widgets** withheld, because an editor that opened on empty zones would offer to save over whatever is really stored.

## The playground [#the-playground]

`/example/zones` is the reference integration and the manual test page: four zones around a locked profile form, blocks from two plugins, a block stored with a variant, an area holding two blocks, and a second area left empty. The page itself draws no button at all: **Edit widgets** appears in the user menu for somebody holding `example.widgets/can_edit`, and nowhere else.

Visit it signed out and it is an ordinary page - shipped defaults, no entry in any menu, no editor chunk. Two checklists on the page say exactly what to look for in DevTools, including the two that matter here: that a save carries one zone rather than the whole page, and that nothing under `src/editor/` is requested until somebody clicks **Edit widgets**.

# End-to-end Example (/docs/dev/widgets/end-to-end)

Everything below is the `@vitnode/example` plugin as it ships, so you can read the finished version in the repository.

```text
define block → register in plugin → blocks() field → create content → ContentRenderer
```

## Define the block [#define-the-block]

```tsx title="plugins/example/src/blocks/callout.tsx"
import type { BlockComponentProps, BlockData } from '@vitnode/core/widgets'

import { defineBlock } from '@vitnode/core/widgets'
import { field } from '@vitnode/core/content'
const calloutFields = {
  body: field.textarea({ required: true, minLength: 1, maxLength: 600 }),
  title: field.text({ required: true, minLength: 1, maxLength: 120 }),
  tone: field.enum({
    defaultValue: 'info',
    values: ['info', 'success', 'warning'],
  }),
}

type CalloutData = BlockData<typeof calloutFields>

const tones: Record<string, string> = {
  info: 'border-primary/40 bg-primary/5',
  success: 'border-success/40 bg-success/5',
  warning: 'border-destructive/40 bg-destructive/5',
}

const Callout = ({ data }: BlockComponentProps<CalloutData>) => (
  <aside
    className={`flex flex-col gap-2 rounded-lg border p-4 md:p-6 ${tones[data.tone ?? 'info']}`}
  >
    <h2 className="text-base font-semibold text-balance md:text-lg">
      {data.title}
    </h2>
    <p className="text-sm leading-relaxed text-pretty md:text-base">
      {data.body}
    </p>
  </aside>
)

export const calloutBlock = defineBlock({
  component: Callout,
  description: 'A short highlighted note in one of three tones.',
  fields: calloutFields,
  id: 'callout',
  name: 'Callout',
})
```

</Step>
<Step>

## Export the plugin's `blocks` module [#export-the-plugins-blocks-module]

The subpath is the registration. Name the file `src/blocks.tsx` so it resolves as `@vitnode/example/blocks`.

```tsx title="plugins/example/src/blocks.tsx"
import type { BlockPluginSource } from '@vitnode/core/widgets'

import { CONFIG_PLUGIN } from '@/const'

import { calloutBlock } from './blocks/callout'

export const blocks = {
  pluginId: CONFIG_PLUGIN.pluginId,
  blocks: [calloutBlock],
} satisfies BlockPluginSource
```

That is the whole registration for the browser. VitNode's Vite plugin finds the module, writes `src/blocks.gen.ts` in every application that configures the plugin, and the block is available as `example:callout`.

Add `namespace: "acme"` here if the derived one - the last segment of the package name - is not the id you want.

</Step>
<Step>

## Give the API the same list [#give-the-api-the-same-list]

The API validates writes, so it needs the definitions too. Pass the **same object**:

```ts title="plugins/example/src/config.api.ts"
import { buildApiPlugin } from '@vitnode/core/api/lib/plugin'

import { CONFIG_PLUGIN } from '@/const'

// [!code ++:2]
import { blocks } from './blocks'

export const exampleApiPlugin = () =>
  buildApiPlugin({
    pluginId: CONFIG_PLUGIN.pluginId,
    // [!code ++:2]
    blocks,
    modules: [adminModule],
  })
```

Passing a different plugin's module is an error - the API and the browser must namespace a block identically or a stored `type` would resolve to two different things.

</Step>
<Step>

## Add a `blocks()` field to a content type [#add-a-blocks-field-to-a-content-type]

```ts title="plugins/example/src/content/page.ts"
import { defineContentType, field } from '@vitnode/core/content'

export const pageContentType = defineContentType({
  id: 'example.page',
  tableName: 'example_pages',

fields: {
    title: field.text({ required: true, minLength: 3, maxLength: 200 }),
    slug: field.slug({ source: 'title' }),
    content: field.blocks({
      allowed: ['core:*', 'example:callout'],
      max: 50,
    }),
  },

publication: true,

publicApi: {
    path: 'pages',
    fields: ['title', 'slug', 'content', 'publishedAt'],
  },
})
```

```ts title="plugins/example/src/database/pages.ts"
import { createContentModel } from '@vitnode/core/content/server'

import { pageContentType } from '@/content/page'

export const pageContent = createContentModel(pageContentType)

export const example_pages = pageContent.table
```

</Step>
<Step>

## Build and migrate [#build-and-migrate]

```bash tab="bun"
bun run build:plugins && bun run db:migrate
```

```bash tab="pnpm"
pnpm build:plugins && pnpm db:migrate
```

```bash tab="npm"
npm run build:plugins && npm run db:migrate
```

</Tabs>

The generated migration is one table with one JSONB column for the zone:

```sql
CREATE TABLE "example_pages" (
	"id" serial PRIMARY KEY,
	"createdAt" timestamp DEFAULT now() NOT NULL,
	"updatedAt" timestamp DEFAULT now() NOT NULL,
	"publishedAt" timestamp,
	"status" varchar(32) DEFAULT 'draft' NOT NULL,
	"title" varchar(200) NOT NULL,
	"slug" varchar(160) NOT NULL,
	"content" jsonb DEFAULT '[]' NOT NULL
);
```

</Step>
<Step>

## Create a record with blocks [#create-a-record-with-blocks]

The generated admin route takes the zone as part of the payload. Give every instance its own stable id.

The generated admin module has no static type to infer from, so it is reached with `rawFetcher` - the same call the AdminCP itself makes.

```ts
import { createBlockInstance } from '@vitnode/core/widgets'
import { rawFetcher } from '@vitnode/core/tanstack/fetcher'

await rawFetcher({
  method: 'post',
  module: 'content/page',
  path: '/',
  pluginId: '@vitnode/example',
  prefixPath: '/admin',
  body: {
    title: 'Build your community',
    content: [
      createBlockInstance('core:hero', {
        title: 'Build your community',
        description: 'Everything you need, in one place.',
      }),
      createBlockInstance('example:callout', {
        title: 'Heads up',
        body: 'Blocks are validated before they are stored.',
        tone: 'info',
      }),
    ],
  },
})
```

`content/page` is the content type's `permissionModule`, derived from the entity half of its id.

Anything the registry refuses - an unregistered block, one the field does not allow, data that breaks a field, two instances sharing an id - is a 422 naming the index of the block at fault. Nothing half-valid is stored.

</Step>
<Step>

## Render it [#render-it]

```tsx title="src/site/pages/page-screen.tsx"
import { ContentRenderer } from '@vitnode/core/widgets/renderer'

import { blocksRegistry } from '@/blocks.gen'

export const PageScreen = ({ page }: { page: PageContent }) => (
  <main className="mx-auto flex w-full max-w-3xl flex-col gap-8 px-4 py-10">
    <h1 className="text-3xl font-semibold text-balance">{page.title}</h1>

<ContentRenderer blocks={page.content} registry={blocksRegistry} />
  </main>
)
```

Read the record with the generated public route - the zone comes back whole, in stored order:

```ts
import { fetcher } from '@vitnode/core/tanstack/fetcher'

const page = await fetcher({
  plugin: '@vitnode/example',
  method: 'get',
  module: 'content/pages',
  path: '/{slug}',
  args: { param: { slug } },
}).then(async (res) => await res.json())
```

That one is fully typed: `pages` is the content type's `publicApi.path`, and the response shape - `content` included - is inferred from the definition.

No extra request is made for the blocks themselves: the definitions came from the plugin configuration when the application started, and nothing re-validates data the write in step 6 already checked.

</Step>
</Steps>

## Where this goes next [#where-this-goes-next]

[Content Zones](/docs/dev/widgets/content-zones) put a name on the place those blocks are rendered, so the step above becomes:

```tsx
<ContentZone id="main" blocks={page.content} registry={blocksRegistry} />
```

The [Visual Editor](/docs/dev/widgets/visual-editor) and [Editable Pages](/docs/dev/widgets/editable-pages) sit on top of exactly this. Clicking **Edit widgets** turns an interactive editing surface on for an authorized moderator: the block catalogue lists what the zone's allowlist resolves to, drag and drop re-orders widgets in place, and the properties panel edits each widget's fields.

# Widgets Overview (/docs/dev/widgets)

A **widget** is a page section somebody can place, in an order they choose: a hero, a paragraph of prose, a call to action, "the six newest articles". A plugin defines it once - the fields it holds and the React component that renders it - and every content type or editable page in the installation can offer it.

```text
Plugin
  ↓ defines widgets (defineWidget)
Widget Registry
  ↓ allowed by a blocks() field or defineEditablePage()
Content record / Page layout
  ↓
ContentZone
  ↓
ContentRenderer / Visual Editor (Edit widgets)
```

## What a widget is made of [#what-a-widget-is-made-of]

| Part          | What it is                                                                                                                                    |
| :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| **Id**        | `hero`, written without a namespace. The registry prefixes the plugin's own, so it is stored as `core:hero`.                                  |
| **Fields**    | Content Engine field descriptors - the same `field.text()`, `field.enum()` and friends a content type uses. There is no second schema system. |
| **Component** | One public React component. It receives the data the record stores for that instance.                                                         |
| **Schema**    | Derived from `fields` at the write boundary. You never write it, and a public render never builds it.                                         |

## What a widget is not [#what-a-widget-is-not]

A widget is **not** a content type. It has no table, no id of its own in the database, no permissions and no API routes. It is a value that lives inside a record or a page layout - which is exactly why re-ordering a page is one `UPDATE` and not a migration.

## Visual editing [#visual-editing]

Widgets power in-place visual editing. Wrap your page's content zones in `<EditablePage>`:

```tsx title="plugins/example/src/pages/settings-page.tsx"
// [!code ++:4]
<EditablePage
  adapter={adapter}
  canEdit={canEdit}
  layout={layout}
  page={settingsPage}
>
  <ContentZone id="before-profile" />
  <ProfileForm />
  <ContentZone id="sidebar" />
</EditablePage>
```

There is no button to write. **Edit widgets** appears in the user menu in the site header whenever a page like this one is on screen and `canEdit` says yes. When an authorized moderator clicks it:

- **Drag and drop**: Rearrange widgets or drag new widgets into allowed zones.
- **Properties panel**: Configure widget settings, variants, and [Layout Areas](/docs/dev/widgets/layout-areas).
- **Zero visitor footprint**: The editor chunk is lazily loaded on click and never ships to ordinary visitors.
- **Layout persistence**: Overrides save directly to `core_page_layouts`—see [Editable Pages](/docs/dev/widgets/editable-pages).
- **Room, not overlap**: The whole site slides over for the sidebar, so nothing you are arranging ends up underneath it.

## How widgets reach an application [#how-widgets-reach-an-application]

Nothing is scanned and nothing is queried. A plugin exports a `widgets` module; VitNode's Vite plugin sees it and writes `src/widgets.gen.ts`, which builds the registry and registers it.

```ts title="src/widgets.gen.ts (generated)"
import {
  createWidgetRegistry,
  setDefaultWidgetRegistry,
} from '@vitnode/core/widgets'

import { widgets as widgets0 } from '@vitnode/core/widgets/built-in'
import { widgets as widgets1 } from '@vitnode/example/widgets'

export const pluginWidgets = [widgets0, widgets1]

export const widgetsRegistry = createWidgetRegistry(pluginWidgets)

setDefaultWidgetRegistry(widgetsRegistry)
```

Installing a plugin is the whole registration step. Removing it takes its widgets with it, and a page that still references one keeps rendering everything else - see [Rendering](/docs/dev/widgets/rendering).

A registry is a plain value, not a service: `createWidgetRegistry` returns an isolated one, and every consumer takes it as an argument. The last line installs it as the process default, which is a convenience for a renderer used without a `registry` prop. Two applications in one process each create their own and pass it explicitly.

Import `src/blocks.gen.ts` **only from a route that renders widgets** - it statically imports every plugin's widget components, so a root module that touches it makes every visitor pay for all of them. The API never needs it: it builds its own registry from the same plugins when it boots, which is what validates every write.

## Where validation happens [#where-validation-happens]

```text
write (untrusted)   →  full schema check, defaults applied  →  JSONB
read                →  nothing
render              →  structural check, every mode
```

Widget data is checked in full once, where it arrives: every create and update runs each instance through its widget's own schema before a row is written, and `ContentRenderer` never repeats that parse. What it does repeat, in every mode, is a cheap structural comparison of the stored object against the widget's current fields - because the write was validated against the definition the widget had _then_, and a plugin can rename a field afterwards. A widget whose stored shape no longer matches is skipped rather than handed to a component that would reach for a key that is gone. [Rendering](/docs/dev/widgets/rendering#validation) has the detail.

## Widgets that ship with core [#widgets-that-ship-with-core]

## Guides [#guides]

# Layout Areas (/docs/dev/widgets/layout-areas)

A zone is a list. Lists go downwards. Pages, unfortunately, also go sideways.

An **Area** is the smallest thing that fixes that: a container stored in the zone, holding a few widgets and one small layout description. It is what you reach for when two widgets belong next to each other, and nothing more than that.

```text
zone
├─ block            a full-width hero
├─ area  2 columns
│  ├─ block         the explanation
│  └─ block         the call to action
└─ block            a closing note
```

{/* Image prompt: A wireframe of one content zone, top to bottom: a full-width block, then a rounded container labelled "Area · 2 columns" holding two blocks side by side, then another full-width block. A small sidebar on the right shows an "Area" panel with a 1-2-3-4 Columns switch, Alignment and Distribution selects under "LAYOUT", and Gap sliders under "SPACING". Dark UI, blue accents, 1600x900. */}

## The three-way split [#the-three-way-split]

This is the idea the whole feature is built on, and it is worth stating plainly:

A block never describes the block next to it. That is why columns are not a field, and why `Area` exists at all.

## The stored shape [#the-stored-shape]

An Area sits in the zone's array, beside the blocks, and is told apart by its `kind`:

```json
[
  { "id": "01JC…HD", "type": "core:hero", "data": { "title": "Welcome" } },
  {
    "id": "01JC…KP",
    "kind": "area",
    "layout": { "columns": 2, "gap": "md", "align": "stretch" },
    "children": [
      { "id": "01JC…R2", "type": "core:text", "data": { "heading": "Left" } },
      { "id": "01JC…T7", "type": "core:cta", "data": { "title": "Right" } }
    ]
  }
]
```

| Key        | Rule                                                                                                                      |
| :--------- | :------------------------------------------------------------------------------------------------------------------------ |
| `kind`     | Always `"area"`. It is the only thing that distinguishes an Area from a block, which is why a block may never declare it. |
| `id`       | The same kind of id a block instance has - stable, unique within the zone, and kept through every move and re-order.      |
| `layout`   | The tokens below. `columns` is required; the rest have defaults.                                                          |
| `children` | Blocks, in rendered order. **Blocks only.**                                                                               |

Array order is rendered order, inside an Area exactly as outside one.

## The layout tokens [#the-layout-tokens]

Four closed sets. Not CSS, not class names - tokens VitNode renders, so a stored layout cannot turn into arbitrary styling smuggled through a content column.

Areas are **mobile-first**: below the `md` breakpoint every Area is one column, whatever `columns` says. Two columns on a 360px screen is not a layout, it is a dare.

## An Area is not a block [#an-area-is-not-a-block]

This is the part worth reading twice, because it is what keeps Areas cheap:

- There is **no `core:area` block**. Nothing registers it, nothing can be installed to provide it, and `registry.get("core:area")` is `undefined` - on purpose.
- It needs **no entry in `allowedBlocks`**. A zone that allows `["core:text"]` still accepts an Area holding `core:text`. The allowlist governs blocks, and the children inside an Area are checked against the very same list as blocks at the zone's root.
- It has **no `data`, no fields and no component of its own**. There is nothing for a properties form to build, which is why the editor shows four selects instead.

In the editor's block catalogue it therefore lives in its own **Layout** section above the plugin groups, rather than pretending to be somebody's block.

```tsx
<ContentZone
  id="settings:sidebar"
  allowedBlocks={['core:text']}
  blocks={content.sidebar}
/>
```

That zone accepts: `core:text` at the root, an Area, and `core:text` inside the Area. It still refuses `core:cta` in both places.

## Areas cannot contain Areas [#areas-cannot-contain-areas]

**In Stage 4, an Area's children are blocks. Never another Area.**

That is enforced everywhere it can be: the drag-and-drop resolver refuses the drop and says so out loud, the catalogue hides the Layout section while an Area is the insertion target, and the API refuses a nested Area on write. A stored document that somehow contains one is shown as unreadable rather than rendered.

<Callout title="Why one level, when the shape would obviously recurse?">
  Because every extra level costs more than it looks. Nesting needs depth limits, cycle detection, an answer for what an allowlist means three levels down, a keyboard drag model that can climb out of a container, and a properties panel that can say *which* area you are editing. One level covers "put these two things side by side", which is what people actually ask for, at a fraction of the surface area.

The shape is ready for it - `children` is a list of nodes, and a nested area would be one more node kind in it - so the door is closed, not locked.

</Callout>

## In the editor [#in-the-editor]

|                  |                                                                                                                                                                                  |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Adding one**   | The **Layout** section of the **Widgets** catalogue holds a single **Area** entry. It drops an empty Area into the targeted zone.                                                  |
| **Filling it**   | Drag a block onto the Area, or use **Add widget** on the Area itself - the sidebar then says _Adding to an area in that zone_, and the Layout section disappears while it is targeted. |
| **Selecting it** | Click the Area's own shell (not a child) and the sidebar shows **Area properties**: Columns, Alignment and Distribution under **Layout**, then Gap and the space above/below and left/right under **Spacing**. Each control re-lays the page out as you pick it. |
| **Ungroup**      | Removes the Area and leaves its children in the zone, at the position the Area held. Nothing is deleted.                                                                          |
| **Delete area**  | Removes the Area **and** its children. A non-empty Area asks first, and offers _Ungroup, keep widgets_ in the same breath.                                                         |

An **empty Area renders nothing at all in public** - no wrapper, no gap, exactly like an [empty zone](/docs/dev/widgets/content-zones#empty-zones). In edit mode it is a visible two-column drop target, because now somebody is looking for a place to put something.

## Reading a zone that may hold Areas [#reading-a-zone-that-may-hold-areas]

A zone is a list of **content nodes**, and a node is a block or an Area. Two helpers keep that from spreading through your code:

```ts
import { contentNodeBlocks, isBlockAreaInstance } from '@vitnode/core/widgets'

isBlockAreaInstance(node) // narrows a node to an Area
contentNodeBlocks(nodes) // every block in the zone, areas flattened away
```

`contentNodeBlocks` is what you want for anything that cares about blocks and not about arrangement: counting them, indexing their text, checking an allowlist. Rendering is already handled - `ContentRenderer` walks nodes and lays an Area out for you.

<Callout title="A migration you do not have to run">
  A zone stored before Areas existed is a list of blocks, and a list of blocks
  is a list of nodes that never nests. Nothing was rewritten, no column changed,
  and a page that never uses an Area keeps exactly the markup it had - the Area
  only exists in the DOM when one is stored.
</Callout>

## When an Area is the wrong answer [#when-an-area-is-the-wrong-answer]

| You want                                       | Use                                                                                                                                            |
| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| Two blocks side by side                        | An **Area**. This is the one.                                                                                                                  |
| One block that looks different                 | A [**variant**](/docs/dev/widgets/block-variants).                                                                                             |
| A different arrangement per breakpoint         | Neither, yet. One arrangement, rendered responsively.                                                                                          |
| A page-wide template - sidebar, footer, header | Several [**zones**](/docs/dev/widgets/content-zones) in your own page markup. An Area arranges content inside a zone; it is not a page layout. |
| Columns inside columns                         | Nothing. See above, twice.                                                                                                                     |

# Rendering Widgets (/docs/dev/widgets/rendering)

## The renderer [#the-renderer]

```tsx title="src/routes/_main/pages.$slug.tsx"
import { ContentRenderer } from '@vitnode/core/widgets/renderer'

import { blocksRegistry } from '@/blocks.gen'

<ContentRenderer blocks={page.content} registry={blocksRegistry} />
  </main>
)
```

For each stored instance it resolves the definition in the registry and renders the component with the instance's own id as the React key - so re-ordering a page moves DOM nodes instead of re-mounting them.

| Prop       | Default                   |                                                                                                                                                                             |
| :--------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blocks`   | —                         | The stored list. `null`, `undefined` and `[]` all render nothing.                                                                                                           |
| `registry` | the process default       | The registry to resolve against. Passing it is the normal way.                                                                                                              |
| `validate` | `"development"`           | `"never"`, `"development"` or `"always"`. It governs the allowlist and the developer warnings, never the structural check - see below.                                      |
| `fallback` | a development-only notice | What to render for a block that cannot be resolved or fails a check.                                                                                                        |
| `allowed`  | none                      | An allowlist to hold the instances to, under the same `validate` gate. [Content Zones](/docs/dev/widgets/content-zones#restricting-what-may-go-in-a-zone) pass theirs here. |

## Where the registry comes from [#where-the-registry-comes-from]

Pass it. `blocksRegistry` is exported from the generated `src/blocks.gen.ts`, and handing it to the renderer is explicit, testable, and works when one process serves more than one application.

<Callout title="Import blocks.gen only where you render blocks" type="warn">
  That file statically imports every configured plugin's block components, so
  anything that reaches it carries all of them. Import it from the route or page
  that renders blocks - never from `router.tsx`, a root layout, or any other
  module the whole application loads. A test asserts the application's root
  router cannot reach it.
</Callout>

Evaluating `src/blocks.gen.ts` also installs that registry as the process default, so a renderer with no `registry` prop finds one. Treat that as a convenience for a renderer deep inside a tree that cannot be handed one, not as setup: it only works if something already imported the file on that route.

The API does not rely on it. It builds its own registry when it boots, from the same plugins' `blocks`, so write-time validation is never waiting on a front end to evaluate a module. With no registry at all, `ContentRenderer` throws a `BlockRegistryMissingError` naming both ways out.

`setDefaultBlockRegistry` returns the function that undoes it, so a test - or a second application - can install one without leaking it:

```ts
const restore = setDefaultBlockRegistry(registry)
try {
  // ...
} finally {
  restore()
}
```

## Validation [#validation]

Block data is validated **once, on write**. Every create and update runs each instance through its block's schema before the row is written, applying defaults and rejecting anything the fields refuse. What is in the column has therefore already crossed a trusted boundary.

So the renderer never repeats that parse. A full Zod parse per block per render is real work on the hot path, and re-running a check the write boundary already made buys nothing.

What it does run, on every render and in every mode, is far cheaper: before a block's component is called, the renderer compares the stored object against the block's fields. Stored data and a block definition drift apart - a field is renamed, a plugin ships a new version, a row is edited by hand - and a component written for today's fields is handed yesterday's object. `data.headline.toUpperCase()` on an object that has no `headline` is a crashed public page, so this one check is not something a mode can switch off.

The check is **structural, not a schema parse**: it reports a field the block no longer declares, a required field that is gone, a `null` in a field that is not nullable, a value of the wrong kind, and a group whose shape no longer matches. It deliberately does not police `minLength`, `max` or enum membership - those are the write boundary's job, and a too-long string is not a reason to blank a section of a live page.

That is what catches the cases where stored data and a block definition have drifted apart:

- a field renamed or made required after records were written
- a row edited by hand in the database
- content imported around the API

None of them can take a page down: the instance is skipped, its component is never called, and everything else renders.

`validate` decides what happens around that check - the allowlist a zone passes in, and what a developer is told:

`validate="never"` is not a way to render data that no longer matches its block. There isn't one, and that is the point - it says "hold nothing to an allowlist", on a page that already trusts what it renders.

Set `validate="always"` on a page rendering block data the API never placed - a live import, a third-party feed - so a zone's allowlist is enforced there as well. It costs a `Map` lookup per block, not a schema parse.

Warnings follow a separate rule, and it is not this one: **nothing is ever logged in production**, whatever `validate` says, because a visitor's console is not a place to report a developer's problem. In development, a block that is not registered, one stored with a variant it does not declare, and an area stored somewhere an area cannot go each warn regardless of `validate` - they say a page is broken, not that a check was asked for. `validate` gates only the allowlist refusal and the drift warning, so `"never"` silences those two and nothing else.

<Callout title="The renderer never transforms">
  Whatever is stored is what the component receives, in every mode. Validation
  decides whether to render an instance; it never fills in defaults or coerces a
  value, so a page cannot look different in development from how it looks in
  production.
</Callout>

## When a block is unavailable [#when-a-block-is-unavailable]

Content outlives plugins. A page may reference `blog:latest-posts` long after the Blog plugin was disabled.

That never takes the page down, in any `validate` mode - resolving a block is a `Map` lookup, and a miss is handled the same way a failed check is.

|                 | Behaviour                                                                                        |
| :-------------- | :----------------------------------------------------------------------------------------------- |
| **Production**  | Nothing is rendered in its place. A visitor sees a page with one section missing, not an error.  |
| **Development** | A dashed notice naming the block and why it was skipped, plus one `console.warn` per block type. |

Pass `fallback` to decide for yourself:

```tsx
<ContentRenderer
  blocks={page.content}
  fallback={({ instance, reason }) =>
    reason === 'unknown-type' ? (
      <PluginMissingNotice type={instance.type} />
    ) : null
  }
/>
```

## Performance [#performance]

A block is a normal React component and the renderer is a loop.

- **No request.** Definitions come from the configured plugins, not from the database. A page of hero + text + image + CTA is exactly as many requests as a page without blocks.
- **No client state.** `ContentRenderer` holds none, subscribes to nothing, and renders on the server like anything else.
- **No validation library.** `defineBlock` and `ContentRenderer` do not reach Zod; the schema machinery lives in the write path. Bundling core's three blocks plus a plugin's, the registry and the renderer comes to about 25 kB of JavaScript with no third-party dependency in it at all.
- **No editor.** `@vitnode/core/widgets` is free of React entirely - it is the metadata surface the API validates with - and `@vitnode/core/widgets/renderer` reaches no drag-and-drop, AdminCP, form or query code. Tests assert the reachable module graph of each entry point, so future editor code cannot drift into the public bundle.

Keep your own block components in that spirit: a block that needs a chart library should `lazy()` it inside its own module, so a page that never places it never pays for it.

## Content Zones [#content-zones]

`ContentRenderer` is the loop. A [Content Zone](/docs/dev/widgets/content-zones) is that loop with a name on it:

```tsx
<ContentZone id="main" blocks={page.content} registry={blocksRegistry} />
```

The name is what lets an editor put something in a particular place later, and what lets blocks sit around application UI that stays locked. A zone renders through this renderer, so everything on this page applies to it unchanged.

# Visual Edit Mode (/docs/dev/widgets/visual-editor)

**Visual Edit Mode** is the part where somebody finally gets to move things around.

A page renders its [content zones](/docs/dev/widgets/content-zones) the way it always has. An authorized moderator opens the user menu in the header, clicks **Edit widgets**, and the _same page_ - same layout, same fonts, same widgets - grows an outline around each zone, makes every widget draggable where it stands, and slides a sidebar that slides in down the right-hand side while the whole site moves over to make room for it. They rearrange, edit in the sidebar, save, and leave. Nobody was sent to a separate admin screen to guess what the result would look like.

```text
public page
   ↓ Edit widgets        ← the user menu, on whatever page you are on
the same page, editable
   ↓ Save
public page again
```

{/* Image prompt: A VitNode settings page in Visual Edit Mode. The left three quarters is a normal-looking settings screen with a profile form in the middle; above and below it, two content zones are outlined with dashed borders and small corner labels reading "Before profile" and "After profile". One block is selected with a blue ring and shows a small floating pill of icon buttons (edit, delete) in its top-right corner. The right quarter is a full-height sidebar headed "Widgets" with a search field and a grouped list of draggable block cards under "CORE" and "EXAMPLE", and a footer with a small amber dot beside "Unsaved changes" and a Discard link, above an eye-icon Preview button, a Finish editing button and a wide blue Save button. Dark theme, 1600x900. */}

## `ContentZone` did not change [#contentzone-did-not-change]

This is the promise the [Content Zones](/docs/dev/widgets/content-zones) page made, and it is worth being specific about how it was kept.

```tsx
<ContentZone
  id="before-profile"
  blocks={content.beforeProfile}
  registry={blocksRegistry}
/>
```

That is the zone in view mode. It is also the zone in edit mode. There is no `EditableContentZone`, no `editable` prop, no second component to migrate to - and nothing stored today needs rewriting.

Internally `ContentZone` asks one question before it renders: _is an edit runtime present?_ In view mode the answer is `null` and the Stage 2 path runs untouched, including the `return null` for an empty zone. In edit mode the runtime answers, and the zone hands it everything it knows - id, blocks, registry, allowlist, wrapper - and lets it render the editing surface instead.

A visitor pays one `useContext` that answers `null`. That is the entire cost of a feature they will never see.

## Turning it on [#turning-it-on]

There are two ways to turn on visual editing, depending on how your page manages layouts.

### 1. High-level: `<EditablePage>` (Recommended) [#1-high-level-editablepage-recommended]

For pages that declare their zones with `defineEditablePage`, wrap your zones in `<EditablePage>` from `@vitnode/core/widgets/page`. It automatically resolves zone data, handles defaults, rebases canonical server responses, and mounts the editor runtime when edit mode is active.

```tsx title="plugins/example/src/pages/zones-page.tsx"
import { EditablePage } from '@vitnode/core/widgets/page'
import { ContentZone } from '@vitnode/core/widgets/zone'
import { createContentEditorAdapter } from '@vitnode/core/content/editor'

const SettingsPage = ({ canEdit, layout, search }: SettingsPageProps) => {
  const adapter = useMemo(
    () =>
      createContentEditorAdapter({
        page: settingsPage,
        save: async (payload) => {
          await savePageLayout(payload)
        },
      }),
    [],
  )

return (
    // [!code ++:4]
    <EditablePage
      adapter={adapter}
      canEdit={canEdit}
      layout={layout}
      openEditing={search.edit === true}
      page={settingsPage}
    >
      <ContentZone id="before-profile" />
      <ProfileForm />
      <ContentZone id="after-profile" />
    </EditablePage>
  )
}
```

No button and no `editing` state: `<EditablePage>` tells the site shell that an editable page this visitor may edit is on screen, and the shell puts **Edit widgets** in the user menu. `openEditing` is only for arriving with edit mode already asked for, which is what a `?edit=true` link does.

See [Editable Pages](/docs/dev/widgets/editable-pages) for the full breakdown of `defineEditablePage`, defaults, and zone permissions.

### 2. Low-level: `<ContentEditorRuntime>` [#2-low-level-contenteditorruntime]

For custom hosts that manage their own raw zone persistence and do not declare an editable page, wrap your zones in `ContentEditorRuntime` from `@vitnode/core/widgets/edit`:

```tsx
import { ContentEditorRuntime } from '@vitnode/core/widgets/edit'

;<ContentEditorRuntime
  adapter={adapter}
  enabled={editing}
  onExit={() => {
    setEditing(false)
  }}
>
  <ContentZone id="before-profile" blocks={content.beforeProfile} />
  <ProfileForm />
  <ContentZone id="after-profile" blocks={content.afterProfile} />
</ContentEditorRuntime>
```

This one takes `enabled` from you, so a custom host that is not an editable page owns edit mode itself - and has to draw its own way in, because the user menu only offers one for a declared page.

### Who gets the button, and where it is [#who-gets-the-button-and-where-it-is]

The entry lives in **the user menu in the site header**, next to My Profile and Settings. That is one place for a site-wide action, it is on every page, and it means a page that happens to be editable does not have to find a corner of its own header to put a button in - which is how three pages end up with it in three different places.

It draws itself from what the page publishes, so there is nothing to render and nothing to wire:

```text
<EditablePage canEdit …>   →   "this page is editable, and this visitor may"
site shell                  →   Edit widgets in the user menu
                            →   the room the sidebar needs, from the whole page
```

`canEdit` is still **yours**. VitNode does not decide who may edit a page, because VitNode does not know what your pages are - a plugin's settings screen, a marketing page and a user profile have three different answers. On editable pages it is usually checked against the moderator permission the page declares (e.g. `widgets: ["can_edit"]`); pass `false` and the entry is not in the menu, the runtime is not mounted, and the editor chunk is not requested.

<Callout title="A hidden button has never stopped anybody" type="warn">
  `/example/zones` reads the visitor's effective moderator permissions in its
  loader and only then says `canEdit`. That is a *signal*, not the boundary: the
  save endpoint behind the adapter asserts the same permission again and answers
  `403` without it. A URL like `?edit=true` is the same kind of thing - it may
  *request* edit mode, and it must never grant it. See [Editable
  Pages](/docs/dev/widgets/editable-pages#can-i-edit-this).
</Callout>

## The lazy-loading guarantee [#the-lazy-loading-guarantee]

The editor is not small. Drag and drop, a block catalogue, a form runtime and a properties panel add up, and every one of them is useless to a visitor reading the page.

So **none of it is in the public page's bundle**. `@vitnode/core/widgets/edit` reaches React and nothing else; the only path from it to the editor is a dynamic `import()` behind `React.lazy`:

```tsx title="packages/vitnode/src/blocks/edit.tsx"
const EditorRoot = lazy(async () => await import('../editor/root'))
```

The chunk is requested when `enabled` first flips to `true` - that is, on the first click of **Edit widgets** - and never before.

```text
view mode      blocks/zone.tsx      → react
edit seam      blocks/edit.tsx      → react
first click    editor/root.tsx      → @dnd-kit, @tanstack/react-form, sonner, …
```

This is enforced, not merely intended. `packages/vitnode/src/editor/boundaries.test.ts` walks the real module graph and fails the build if the arrow ever points the wrong way:

- `blocks/zone.tsx` and `blocks/edit.tsx` **eagerly** reach `react` and nothing else;
- neither reaches `@dnd-kit/*`, `@tanstack/react-form`, `sonner`, `@tanstack/react-query`, `@tanstack/react-router`, `cmdk` or `zod`;
- `blocks/edit.tsx` **does** reach `@dnd-kit/core` once dynamic imports are followed, which is the proof that the only path is a dynamic one;
- nothing under `src/editor/**` reaches `views/admin/**`, or any database or server package;
- the sidebar is the one panel `editor/root.tsx` mounts, `editor/toolbar/` and `editor/block-picker/dialog.tsx` do not exist, and the editor no longer reaches `cmdk` at all - a revert fails the test instead of quietly shipping a modal again.

Turning that static `import` back on would be a one-line change and a silently 200 kB heavier home page. The test is the thing that notices.

## Turning it on does not restart your page [#turning-it-on-does-not-restart-your-page]

Lazy loading is easy to get right in a way that quietly breaks the page underneath. The obvious shape is this one:

```tsx
if (!enabled) return <>{children}</>

return (
  <Suspense fallback={children}>
    <EditorRoot>{children}</EditorRoot>
  </Suspense>
)
```

It looks like a toggle. It is a **remount**. React reconciles by position in the element tree, so the moment a wrapper appears above `children`, everything in them is torn down and built again: `useState` resets, uncontrolled inputs empty themselves, focus is lost, a playing video restarts. Reusing the identical `children` element object does not help - position is what counts, and `<Suspense>` alone is enough to do it.

That is not acceptable on a page somebody is already using. So the runtime is built the other way round:

```text
site shell <div>                ← above the header, padding is the only thing on it
  ContentEditorRuntime          ← public, always mounted
    ContentEditContext.Provider ← always mounted, value is null in view mode
      {children}                ← one fixed slot, never moves
      {enabled && <Suspense><EditorRoot/></Suspense>}   ← a SIBLING
```

The editor is never an ancestor of your page. Turning edit mode on changes one context value and mounts a sibling; nothing above `children` changes, so nothing in them remounts.

The site shell above it all is a plain block `<div>` at the document root, and it stays one whether or not anybody is editing. That is deliberate rather than incidental: **padding only transitions between two values of an element that already has a box**, so a wrapper that appeared when editing started - or went back to `display: contents` when it ended - would snap to its new width instead of gliding there, in whichever direction it was going. It carries the transition and the two custom properties and nothing else.

### Then how do zones become editable? [#then-how-do-zones-become-editable]

`@dnd-kit` needs its `DndContext` above every droppable, and the zones are inside your page. Since the editor may not wrap your page, the zones come **out** to it instead.

In edit mode `ContentZone` renders a bare host element - your `as`, your `className`, the usual `data-vitnode-zone` attributes - and registers that DOM node with the runtime. The editor, which owns the `DndContext`, renders the real `EditableZone` into each registered node with `createPortal`:

```text
page             editor
────             ──────
<aside ref>  ←   createPortal(<EditableZone/>, node)
                   inside <DndContext>, inside the editor's own providers
```

The markup lands where you put the zone; the React tree it belongs to is the editor's. One consequence is worth knowing: a block rendered in a zone reads React context from the **editor**, not from inside your page subtree. Context from your app root reaches it as usual - the router, the theme, the intl provider - but a provider you render _between_ your page and a `ContentZone` will not. No built-in or plugin block relies on that today, and if yours does, pass the value through the block's own data instead.

## The interaction model [#the-interaction-model]

A block is a real component. It contains links, buttons, forms, embedded video - things that do something when you click them. In edit mode, clicking one has to mean _select this block_, not _follow this link_.

VitNode solves that with three layers on every block, and one escape hatch:

|                         |                                                                                                                           |
| :---------------------- | :------------------------------------------------------------------------------------------------------------------------ |
| **`inert` container**   | The block's own component renders inside an `inert` element, so nothing in it can be clicked, focused or tabbed to.       |
| **Transparent overlay** | A full-size `<button>` above it. Clicking anywhere on the block selects it; screen readers get _"Select the Hero block"_. |
| **Floating actions**    | Edit and Delete appear on hover, on focus, and while selected. There is no move button: the widget itself is the handle. |
| **Preview toggle**      | Removes all three. The block becomes the real thing again, exactly as a visitor sees it.                                  |

The alternative - asking every block author to make their component "editor-aware" - was never on the table. A block's component is public rendering code, it is written by plugin authors who have never read the editor's source, and it must not grow a second mode. `inert` does the whole job in one attribute, from the outside.

Preview is there because the illusion has to break sometimes. Does the video play? Does the accordion open? Is the call-to-action button the right size once it is actually hoverable? Toggle Preview, use the page like a visitor, toggle back.

## Empty zones become visible [#empty-zones-become-visible]

An empty zone [renders nothing at all](/docs/dev/widgets/content-zones#empty-zones) in view mode - no wrapper, no placeholder, no gap. That is deliberate, and it stays true.

In edit mode the same zone renders a dashed drop target with its name and an **Add block** button, because now somebody _is_ looking for a place to put something.

That name is the zone's id made readable, so nobody has to decode your naming scheme: hyphens become spaces, the first letter is capitalised, and each `:` scope becomes its own part.

The same name is used in the sidebar (_Adding to Before profile_) and in what screen readers announce during a drag. The id itself is untouched - it is still what gets stored and what you write in code.

```text
view mode   before-footer   (nothing)
edit mode   before-footer   ┌ dashed box ┐
                                     │ + Add block │
                                     └────────────┘
```

Finish editing and it disappears again. A page with eight placement points and two filled ones costs two in public, and shows all eight to the person arranging them.

## The editing sidebar [#the-editing-sidebar]

Everything the editor asks of you lives in one panel down the right-hand side: the block catalogue, the properties of whatever is selected, and the **Preview** / **Discard** / **Save** / **Finish editing** row at the bottom. There is no modal to open and dismiss, and no second panel competing for the same corner of the screen.

The **whole site** is padded, not covered - the header, the page and the footer all move over together, the way the AdminCP dashboard moves over for its widget panel. So the sidebar never sits on top of anything: not the zone you are arranging, and not the user menu you opened it from. Below `md` the same sidebar becomes a bottom sheet, because 360px of a phone is not a sidebar, and the padding moves underneath the site instead.

Both halves of that take 200ms and start on the same frame, in both directions: the page's edge and the sidebar's edge are the same number on every frame of it. **Finish editing** plays the whole thing backwards - the editing chrome goes at once, so the page is public again immediately, and the editor stays mounted just long enough for the sidebar to slide back off screen while the padding shrinks under it.

Which frame that is comes from the **editor**, not from the seam that loads it. On a first open the editor chunk and the sidebar's own messages take a moment to arrive, and a shell that started widening the moment edit mode was _requested_ would slide the page over to make room for a sidebar that had not loaded yet - the page moving first and the panel catching up, once, on the first click only. So `editor/root.tsx` is what asks the shell for its room, and it cannot ask before it exists. Nothing moves until the sidebar is ready; then everything moves together.

### One panel, three modes [#one-panel-three-modes]

|                     |                                                                                                                                                                                  |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Widgets**         | A search field, a **Layout** section holding the [Area](/docs/dev/widgets/layout-areas) entry, and every block this location accepts, grouped by the namespace that provides it. |
| **Properties**      | The selected block's name and type in the header, next to Duplicate and Delete, then its [variant](/docs/dev/widgets/block-variants) picker and its fields.                     |
| **Area properties** | Duplicate, Ungroup and Delete area in the header, then the Area's **Layout** (Columns, Alignment, Distribution) and **Spacing** (Gap and the space around it).                  |

Selecting a block switches to **Properties**; selecting an Area switches to **Area properties**. Each panel keeps its header pinned while its content scrolls, so the actions never scroll out of reach. The **←** button at the top (_Back to widgets_) switches back from either _and_ clears the selection, so the page stops ringing something you are no longer editing. Deleting the selection does the same thing on its own.

The footer keeps the state of the page in one glance: a coloured dot and a word (**Saved**, **Unsaved changes**, **Saving…**, **Save failed**), **Discard changes** beside it, and underneath **Preview**, **Finish editing** and **Save** - the only blue button in the panel, lit up only when there is something to save.

In **Preview** the sidebar collapses to a slim bar holding **Back to editing** and **Finish editing**. It never collapses to nothing - a preview you cannot leave is a trap - and the editor stays mounted behind it with every unsaved change intact.

## Two ways to add a block [#two-ways-to-add-a-block]

A catalogue entry is a drag source _and_ a button, because those answer two different questions.

|              |                                                                                                                                  |
| :----------- | :------------------------------------------------------------------------------------------------------------------------------- |
| **Drag it**  | You care where it goes. An insertion line shows the exact position while you are still holding it.                               |
| **Click it** | You do not, or you already said where. It goes to the targeted zone - or, with nothing targeted, the first zone that accepts it. |

**Add widget** on a zone is what sets that target: the sidebar switches to **Widgets**, its header shows _Adding to Sidebar_, and the zone stays lit until a block lands or you clear it. **Add widget** on an Area targets the Area instead, and the header says so - _Adding to an area in After profile_ - because naming the zone alone would be a lie about where the block is going.

The catalogue's own **Layout** section sits above the plugin groups and holds one entry: **Area**. It works exactly like a block entry: click it and an empty Area drops into the target, or drag it and it lands where the insertion line says. An Area is not a registered block and has no type, so what travels with the drag is the layout itself rather than a block id - and dropping one onto an Area is refused, because [an Area cannot hold another Area](/docs/dev/widgets/layout-areas#areas-cannot-contain-areas). While an Area is the insertion target the Layout section disappears for the same reason.

Either gesture inserts the block, selects it and opens **Properties** in one step, so the next thing you do is fill it in. The new block fades in where it landed and scrolls into view if it landed off screen - handy when a click sent it to the bottom of a long page.

### How a drag feels [#how-a-drag-feels]

A drag is meant to feel like picking something up, not like watching a diagram.

|                    |                                                                                                                                                              |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Picking up**     | The card lifts a touch (2% larger, deeper shadow). The place it came from turns into a dashed slot, so you can see the gap you are about to leave.           |
| **Moving**         | Every zone that accepts what you hold lights up softly; the one under the pointer lights up fully. Zones that refuse it dim instead of shouting in red.      |
| **Dropping**       | The card settles into its new slot in 200ms, shrinking back to its real size on the way. Drop a catalogue card nowhere useful and it glides back home.       |
| **Reduced motion** | With _reduce motion_ switched on in the operating system, all of the above happens instantly - same feedback, no movement.                                 |

### The catalogue follows the target [#the-catalogue-follows-the-target]

`allowedBlocks` on a zone is what the catalogue offers. Not everything installed - everything **allowed** in that location.

```tsx
<ContentZone
  id="sidebar"
  allowedBlocks={['core:text']}
  blocks={content.sidebar}
/>
```

Target that sidebar and the catalogue shows exactly one block. Clear the target and it shows the union of what the page's zones accept, because now any of them could be the destination. Same `allowedBlocks` value, same format as a [`blocks()` field's `allowed`](/docs/dev/widgets/blocks-field#restricting-what-may-go-in), now doing a third job.

A zone that allows nothing the installation provides says so, rather than offering an empty list.

<Callout title="The catalogue is not the write boundary">
  The allowlist on a zone describes a location. The one on the `blocks()` field
  **enforces**, on every create and update. The catalogue filtering by the
  zone's copy is a courtesy to the person editing - the field is what refuses a
  block that should never have been stored.
</Callout>

## Drag and drop [#drag-and-drop]

Grab a block anywhere on it, or a catalogue entry anywhere on its card, and move it. A click without moving still just selects the block, and an Area is dragged by its own frame - its header or the space around its columns - so grabbing a widget inside an Area moves that widget, not the Area. On a touchscreen a swipe keeps scrolling the page; press and hold to pick a widget up.

- **Reorder** inside a zone: drop it above or below a sibling.
- **Move across zones**: drop it into another zone, or onto one of that zone's blocks to land at that position.
- **Into an empty zone**: drop it anywhere on the dashed placeholder.

Identity is the block instance id throughout - never an array index - so a block that crosses a zone keeps being the same block, with the same data, and the properties panel does not blink.

### Before or after, never into a block [#before-or-after-never-into-a-block]

Dropping onto a block inserts **before** it or **after** it, decided by which half of it the pointer is over. That blue line is the answer, shown before you let go.

Nothing ever lands _inside a block_. Dropping **into** something is the Area's gesture: drag a block onto an [Area](/docs/dev/widgets/layout-areas) and it becomes one of that Area's children, at the position the line shows. Drag a child back out and the Area keeps the rest. An Area dropped onto another Area is refused out loud - _An area cannot hold another area_ - rather than silently landing beside it.

### The keyboard does all of it too [#the-keyboard-does-all-of-it-too]

Drag and drop that needs a mouse is drag and drop half the people cannot use, so every block is a real button and every gesture has a key.

The blue insertion line follows a keyboard drag exactly as it follows a pointer, because both are the same line: the editor asks its drop resolver where this block _would_ land right now and draws the answer. Nothing is measured twice, so the line cannot disagree with the drop - and when the answer is "nowhere" (the zone refuses the block, or it already sits in that spot) there is no line, which is the honest thing to draw.

Screen readers get the same story in words. The editor localises dnd-kit's announcements through `core.editor.dnd.*`, so picking a block up, passing over a zone, being refused by one, and landing all read out with the **block's name and the zone's id** rather than the instance ids dnd-kit would otherwise spell aloud.

```text
Picked up Callout.
Callout is over the after-profile zone, position 1 of 2.
The sidebar zone does not accept Callout.
Callout was dropped into the after-profile zone, position 1 of 2.
```

### An incompatible target refuses [#an-incompatible-target-refuses]

Drag an `example:callout` toward a zone that allows `core:text` only and the zone turns red and says it does not accept what you are dragging. Let go and nothing happens: a block stays where it was, a catalogue entry is simply not inserted.

The refusal is computed from the same `isBlockAllowed` the field and the catalogue use. One allowlist format, one function that evaluates it, three places that ask.

## The properties panel [#the-properties-panel]

Select a block and its fields appear in the sidebar: text, textarea, number, boolean, enum, date-time, and groups of those - the [field kinds a block may hold](/docs/dev/widgets/defining-a-block#which-fields-a-block-may-hold), as declared by `defineBlock`. The panel builds itself from the block definition, so a block that adds a field gets a control for it with no editor change at all.

Typing updates the block on the page **as you type**. There is no Apply button, and no preview pane to compare against, because the page _is_ the preview.

A block that declares more than one [variant](/docs/dev/widgets/block-variants) gets a **Variant** picker above those fields. Picking one is a separate action from editing content: it keeps the instance's id, leaves `data` untouched, and does not reset a field you were halfway through. A block with one variant, or none, shows no picker - there is nothing to decide. A stored variant the block no longer offers is named in the panel, with the declared ones still offered beside it.

### Area properties [#area-properties]

Select an [Area](/docs/dev/widgets/layout-areas) rather than one of its children and the same sidebar shows its layout in two groups - **Layout** (**Columns** as a one-click 1–4 switch, **Alignment**, **Distribution**) and **Spacing** (**Gap** and the space around the Area) - and re-lays the page out as you pick them. **Duplicate area**, **Ungroup** and **Delete area** sit in the panel's header.

Ungroup and Delete are deliberately different buttons. Ungroup removes the container and leaves the blocks where the Area was; Delete takes them with it, and asks first, offering _Ungroup, keep blocks_ in the same dialog. An Area holding nothing is deleted without the interrogation, because there is nothing to lose.

A block whose stored data does not match what its definition declares is not editable here - it is flagged on the page instead. Editing it would mean guessing which half is wrong, and guessing is how content gets quietly destroyed.

## Content the editor cannot read [#content-the-editor-cannot-read]

A zone is handed whatever is stored in it, and storage is older than any editor. A field can hold a value from a migration that never finished, from a plugin that wrote its own shape, or from a hand-edited row. The editor has to have an answer for that, and the answer is **never delete it**.

Every value a zone mounts with is sorted into one of two piles:

|                                   |                                                                                                                                                                           |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **A block with bad data**         | `{ id, type, data }` is intact and `type` is registered, but `data` does not match the fields. It stays a block: selectable, movable, deletable.                          |
| **Something that is not a block** | No usable `id`, no `type`, an id already used **by an earlier block in the same zone**, or not an object at all. Nothing can be inferred from it, so nothing pretends to. |

The first pile keeps working exactly as before - the block renders an [`InvalidBlock`](#the-properties-panel) placeholder in place of its component, and its own shell stays draggable and keeps its delete button. Its data is bad; its identity is not.

The second pile never becomes a content node. It is kept beside them, not among them:

```ts
interface EditorZoneState {
  nodes: readonly ContentNode[]
  invalid: readonly { index: number; value: unknown }[]
  // …
}
```

A `ContentNode` is a block instance or an [Area](/docs/dev/widgets/layout-areas). An Area whose stored `layout` is not one the editor recognises, or which holds an Area of its own, lands in the second pile with everything else: shown as-is, never rewritten.

Nothing in the editor - no reducer action, no drop resolver, no block component - is ever handed one of those values. The zone shows them at the top, prints what each one looks like, and offers exactly one action per entry: **Remove invalid entry**.

### One id per zone, not one id per page [#one-id-per-zone-not-one-id-per-page]

An instance id has to be unique **within its zone**, and only within its zone. Two blocks sharing an id in one zone are indistinguishable there, so the second one goes in the opaque pile above. Two blocks sharing an id in two _different_ zones are perfectly valid - the Content Engine validates a blocks field on its own, so nothing has ever promised otherwise, and a zone copied from one field into another would trip over any rule that did.

The editor therefore never identifies a block by its id alone. Selection, updates, deletion, duplication, moves and drag-and-drop all carry the zone:

```ts
interface EditorBlockRef {
  blockId: string
  zoneId: string
}
```

Drag-and-drop ids are built the same way - `blockDraggableId({ zoneId, blockId })` percent-encodes both halves, so an id survives a round trip whatever characters it contains - and the drag payload carries the ref structurally rather than being parsed back out of a string. Selecting the copy of `X` in the sidebar zone can never edit the copy of `X` above the profile form.

Zone ids run the other way: a zone id is a _place_, so one page may only have one of each. Two `<ContentZone>`s claiming the same id while the editor is open is a [developer error](/docs/dev/widgets/content-zones#one-id-one-place-on-the-page), not a merge.

### Saving is blocked until you decide [#saving-is-blocked-until-you-decide]

While a zone still holds one, the whole editor refuses to save. The **Save** button is disabled, the sidebar footer explains why, and the adapter is not called even from **Save and finish**:

> This zone contains invalid or legacy content that the Visual Editor cannot safely save. Resolve or explicitly remove the invalid content before saving.

That is deliberate, and it is the whole point of the pile. The save payload is a **replacement** array per zone - the editor hands over the blocks it understands, and the API stores exactly that. If a value the editor could not read were quietly left out of that array, editing an unrelated block in the same zone would delete it. Storing `[A, malformed, B]` and saving after a change to `A` would write `[A2, B]`, and nobody would ever be told.

So removal is a decision you make, one entry at a time, and it is an edit like any other: **Discard** brings the entries back, and the page is dirty until you save.

## Zones that leave the page [#zones-that-leave-the-page]

A page is allowed to change its mind. A tab, a feature flag, a route transition - any of them can stop rendering a `ContentZone` while edit mode is still on, and the editor has to have an answer that is not "persist it anyway".

When a zone's outlet unmounts it is **removed from the document**: out of `zones`, out of `order`, and therefore out of the next save payload entirely. A stale zone can never be written back. If it owned the selection, the selection clears and the sidebar returns to **Widgets**; if it was the target of **Add widget**, that target clears too.

What happens to unsaved work in it depends on whether there was any:

|                        |                                                                                                                                      |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| **No unsaved changes** | It is dropped silently. There was nothing to lose.                                                                                   |
| **Unsaved changes**    | It is still dropped - the zone is gone, there is nowhere to put them back - but the sidebar footer names it, so it is never _quiet_. |

That is the rule: an unmounted zone is out of the editable document, and losing work to it is reported rather than blocked. Blocking **Save** would trap you on a page whose zone no longer exists, and keeping the zone would mean writing content the page has stopped showing. Bring the zone back and it re-mounts from whatever the page hands it, with a fresh baseline.

What the _host_ does with the gap is the host's call, and it matters. The save payload only carries zones the editor currently holds, so a save must write **only what it names** - never a whole field set composed on top of a fallback, which is how a zone that is off the page gets reset to something nobody chose. [Editable Pages](/docs/dev/widgets/editable-pages#the-two-routes) does exactly that: a zone the payload does not mention is not written, because each zone is its own row.

## Saving is the host's job [#saving-is-the-hosts-job]

The editor never fetches. Not once. The only way anything leaves it is the adapter you passed:

```ts
type VisualEditorSnapshot = Readonly<Record<string, readonly ContentNode[]>>

interface VisualEditorSaveInput {
  changedZoneIds: readonly string[]
  expectedZones: VisualEditorSnapshot
  zones: VisualEditorSnapshot
}

interface VisualEditorSaveResult {
  revision?: string
  zones?: VisualEditorSnapshot
}

interface VisualEditorAdapter {
  save: (
    input: VisualEditorSaveInput,
  ) => Promise<VisualEditorSaveResult | void> | VisualEditorSaveResult | void
}
```

`zones` holds every zone on the page keyed by its id; `changedZoneIds` names the ones that actually differ from what loaded; `expectedZones` holds, under the same keys, the **baseline** each zone started from - what was there before anybody dragged anything. Resolve and the editor marks itself clean and toasts. Throw or reject and it shows an error and keeps the changes, so nothing is lost to a failed request.

Send the baseline with the write and your API can answer the only question that matters when two people are arranging one page: _is the thing I am replacing still the thing I was given?_ Zones are independent, so two moderators editing different zones both succeed, while a write to a zone that moved underneath somebody is refused instead of silently winning. [Editable Pages](/docs/dev/widgets/editable-pages#two-moderators-one-page) does exactly that with a `409`, and the editor says so - _Somebody else saved this page first_ - while keeping every change you made.

The one rule the contract asks of you: **save what you were handed**. The editor rebases its idea of "unchanged" onto the snapshot it sent, not onto the state it is in when the promise resolves - so a word typed while the request was in flight is still unsaved afterwards, exactly as it should be.

`zones` is a **complete** picture of the page, not a patch: every zone the editor mounted is in it, emptied ones included. `changedZoneIds` names the ones that differ from what loaded - send those, and leave everything else alone at the other end. What you must not do is send a partial write and let the rest fall back to defaults.

<Callout title="You probably do not write this by hand">
  If the page declares its zones - and it usually should -
  `createContentEditorAdapter` builds this payload for you, from the same page
  definition the server reads. See [Editable
  Pages](/docs/dev/widgets/editable-pages). The rest of this section is the
  contract underneath it, and what to honour if you are writing an adapter for
  somewhere else.
</Callout>

```tsx
const adapter = useMemo<VisualEditorAdapter>(
  () => ({
    save: async ({ changedZoneIds, expectedZones, zones }) => {
      await fetcher({
        plugin: '@vitnode/example',
        method: 'patch',
        module: 'pages',
        path: '/{id}/zones',
        args: {
          param: { id: page.id },
          json: { changedZoneIds, expectedZones, zones },
        },
      })
    },
  }),
  [page.id],
)
```

### Answer with what you stored [#answer-with-what-you-stored]

`save` may resolve with nothing, and the editor is happy either way - but it is better if it does not. What the client sent and what the server kept are not always the same thing: an API is allowed to reorder, normalise, drop or rewrite what it is given. If the editor rebases onto its own input, it goes clean against a version that never existed, and the next save pushes the stale copy back.

So return what you stored:

```tsx
const [zones, setZones] = useState(loaderData.zones)

const save = async (input: VisualEditorSaveInput) => {
  const payload = await writeChangedZones(input)

setZones((current) => ({ ...current, ...payload.zones }))

return { zones: payload.zones }
}
```

The editor then adopts that snapshot as its baseline **and** as what you are looking at - unless you edited during the request, in which case your edit stays and the zone remains dirty against the new baseline. Both halves matter: the first stops the stale re-send, the second is the [save race](#save-stays-finish-editing-leaves) rule that has always applied.

Updating the page's own state does the other half of the job: **Finish editing** shows the saved page immediately, with no reload, because the page underneath is already the new one.

This belongs to the page, not to the editor. The editor owns no layout state and never will: it is handed blocks, it hands back blocks, and the content's owner decides what is true.

### Content that changes underneath the editor [#content-that-changes-underneath-the-editor]

The same problem arrives from the other direction. A router invalidation, a refetch, or the `setZones` above all re-render your page with different `blocks`, and a zone that is already mounted has to decide what to do with them.

The rule is the one you would write yourself:

|                   |                                                                                                                                                   |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Zone is clean** | The incoming content replaces both the working copy and the baseline. The zone adopts it and stays clean. A selection whose block is gone clears. |
| **Zone is dirty** | Nothing about its content moves. Local edits win until **Save** or **Discard** resolves them. Only the allowlist and registry still refresh.      |

There is deliberately no merge. Two block arrays cannot be reconciled without inventing an answer, and inventing one is how an editor loses a paragraph somebody typed.

### A failed load is not an empty page [#a-failed-load-is-not-an-empty-page]

Loading has a trap that is easy to walk into and expensive to walk out of. A route answers three different "there is nothing here" shapes, and they mean three different things:

|                             |                                                                                                |
| :-------------------------- | :--------------------------------------------------------------------------------------------- |
| **200, an empty zone**      | Nothing is in that zone. Editing and **Save** are fine.                                        |
| **200, nothing stored yet** | The page has never been rearranged, so its declared defaults come back with `updatedAt: null`. |
| **Anything non-2xx**        | What is stored is **unknown** - an auth failure, a database error, a dropped connection.       |

Treating the third as the first is how a page overwrites content nobody meant to touch: the load fails, something plausible renders as if it had been read, somebody tidies a heading, presses **Save**, and the real stored layout is gone. The editor cannot catch this, because by then it was handed a perfectly valid set of blocks.

So the playground loader refuses:

```ts
if (!stored.ok) {
  throw new Error(`Reading this page's layout answered ${stored.status}…`)
}
```

The router's `defaultErrorComponent` takes it from there, and **Edit widgets** is never reached. The API holds the same line from the other side: a stored row that cannot be read throws rather than answering with an empty layout.

The second row is a _success_, and the distinction is the whole reason a page declares its defaults rather than inventing them at render time. Defaults that came from the declaration are content somebody shipped on purpose, so the first **Save** is entitled to replace them; defaults invented because a read failed are content nobody chose. [Editable Pages](/docs/dev/widgets/editable-pages#the-two-routes) has the longer version.

If throwing does not suit your route, return an explicit error state and disable editing on it. What you must not do is hand the editor a writable copy of something you did not actually read.

### Save stays, Finish editing leaves [#save-stays-finish-editing-leaves]

Two buttons, two different jobs, and it is worth being blunt about which is which.

|                        |                                                                                                                                        |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| **Save**               | Runs the adapter and **stays in edit mode**. The footer goes from _Unsaved changes_ to _Saved_ and you carry on arranging.             |
| **Finish editing**     | Leaves edit mode. With nothing unsaved it just leaves.                                                                                 |
| **Finish while dirty** | Asks first: **Save and finish** (saves, then leaves - and stays put if the save fails), **Leave without saving**, or **Keep editing**. |

Saving is not an exit, because the most common thing anybody does after saving is keep going. And leaving is not a save, because an editor that silently writes on the way out is an editor nobody trusts. **Discard** is the third option and the only one that throws work away - it puts every zone back to what loaded.

The same question is asked by the browser: navigate away with unsaved changes and the guard prompts before the page goes.

### Why there is no zones table [#why-there-is-no-zones-table]

The obvious alternative is a `core_content_zones` table that stores `(zoneId, blocks)` for every page in the installation, and a generic save endpoint that writes to it. It was not built, on purpose.

Block content already lives somewhere: in a [`blocks()` field](/docs/dev/widgets/blocks-field) on a content type, in a plugin's own settings row, in whatever column the page loads it from. A generic zones table would be a **second** home for the same data, and then two places to migrate, two permission models, two revision histories, and a stubborn class of bug where the page renders one copy and the editor saves the other.

The adapter is the alternative: the page that knew how to _load_ its zones is the page that knows how to _save_ them. It writes to its own column, through its own API, behind its own permission check.

What is generic is the _wiring_, not the storage. [Editable Pages](/docs/dev/widgets/editable-pages) is the one exception, and it earns it: a settings screen's zones belong to no record, so core keeps them in an internal table keyed by the page id - one row per page, holding only the zones somebody customised - and the page declares its zones instead of mapping them. A zone whose blocks _do_ live on a content type stays where it always lived, and the page that knew how to load it is still the page that knows how to save it.

## What the editor deliberately does not do [#what-the-editor-deliberately-does-not-do]

Being clear about the edges is more useful than a roadmap.

|                                   |                                                                                                                                                                                                                                                                                                                                                    |
| :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nested areas**                  | An [Area](/docs/dev/widgets/layout-areas) holds blocks, one level deep. No areas inside areas, and no block that contains a zone of its own.                                                                                                                                                                                                       |
| **Drafts and revisions**          | Save writes. There is no "unpublished version of this page" concept in the editor.                                                                                                                                                                                                                                                                 |
| **Permission UI**                 | No roles screen. Who may edit is your page's answer, and the save route's; an [editable page](/docs/dev/widgets/editable-pages#can-i-edit-this) names the moderator permission it wants, but granting it is the ordinary staff screen's job.                                                                                                       |
| **Layout administration**         | No AdminCP section listing which pages have been rearranged, no reset-to-default, no export or import, no copying one page's layout onto another. [Deliberately left to a possible V2](/docs/dev/widgets/editable-pages#where-a-layout-is-stored) - the storage shape makes each of them a query on one table, but none is built.                  |
| **Live collaboration**            | No shared cursors, no presence, no merging two people's edits to **one** zone. Different zones of one page do merge, and a stale write to the same zone is refused rather than applied - see [two moderators, one page](/docs/dev/widgets/editable-pages#two-moderators-one-page) - but nobody watches anybody else arrange anything in real time. |
| **File and relation fields**      | The properties panel edits the [field kinds a block may hold](/docs/dev/widgets/defining-a-block#which-fields-a-block-may-hold). Blocks cannot hold uploads or references yet, so neither can the panel.                                                                                                                                           |
| **Responsive breakpoint editing** | One arrangement, rendered responsively by the blocks themselves. No per-breakpoint layouts.                                                                                                                                                                                                                                                        |
| **Rich text**                     | A `text` or `textarea` field is a plain string, and it stays one. You type into it in the properties panel, and no block field holds bold, links or lists. Tiptap ships in this repository and is deliberately nowhere near a block.                                                                                                               |

Everything in that table is a _later_ decision rather than a closed door - but none of it is built, and none of it is implied by the APIs above.

## Known limitations [#known-limitations]

The section above is about scope. This one is about rough edges in the part that _is_ built - the things you will notice, written down so you do not have to discover them.

**A pointer drag's spoken position lags the line it draws.** The insertion line updates continuously, but the screen-reader announcement is only refreshed when the block underneath the pointer changes - move from a block's top half to its bottom half and the line jumps, the sentence does not. That is deliberate: the alternative is announcing on every pixel of movement, which floods a live region until it is useless. Keyboard dragging is unaffected, because every arrow key changes the target.

**Locked application UI is not dimmed.** In edit mode the zones are outlined and labelled, and everything else on the page - your forms, your navigation, your buttons - looks exactly as it did. Nothing says "this part is not editable" except the absence of an outline.

Dimming it would mean fading the page and un-fading the zones, and a descendant cannot undo an ancestor's `opacity` or `filter`: those create a new compositing context that the zone inside it is stuck in. The only other route is selector-based - "dim everything that does not contain a zone" - which would have to make assumptions about a page's DOM that VitNode does not get to make, since the page is yours. So the editor emphasises the zones rather than de-emphasising the page, and a host that wants more can style `[data-vitnode-zone]` and its surroundings itself.

**Mobile is a bottom sheet, and only that.** Below `md` the sidebar becomes a sheet so it does not eat a phone screen. The page reserves room for it - `--editor-sheet-height` is padding on the canvas below `md` and the width of the sidebar above it, so the last zone always scrolls clear of the sheet and Preview takes both away - but nothing is _tuned_ for touch: a drag competes with page scrolling, and press-and-hold is the only way to tell a drag from a scroll. Arranging a page on a phone is possible. Enjoyable is a later stage.

**Blocks themselves do remount when you enter edit mode.** The page around them does not - that is the whole point of the [stable boundary](#turning-it-on-does-not-restart-your-page) - but a `ContentZone` genuinely swaps what it renders, from `ContentRenderer` output to the editor's portal, so each block component is built again. A block holding transient state of its own restarts with it: a playing video, an open accordion, a carousel's position, a `useState` counter. Content survives, because content lives in the block's data; ephemeral UI state does not. Closing that gap means hoisting block instances above the view/edit split, which is a bigger change than this stage is willing to make.

**A zone's blocks render in the editor's React tree, not your page's.** The consequence of the portal described [above](#then-how-do-zones-become-editable): context from your app root reaches a block as usual, context you provide between your page and a `ContentZone` does not. Nothing ships today that needs it, and the fix if you do is to put the value in the block's data.

**There is no end-to-end test harness.** The pure logic is covered by vitest - the reducer, the drop resolver and its insertion placement, zone drop states, the save input, the catalogue, and the module-graph boundary test that keeps the editor out of public bundles. What no test covers is a real browser actually dragging something, so the [manual checklist](#verifying-it-yourself) is the regression suite for gestures. `apps/web` has no test runner configured at all, which is why the checklist lives in this page rather than in a spec file.

## What used to be an extension point [#what-used-to-be-an-extension-point]

Two rows of that table were designed _around_ rather than merely skipped, and both have since landed. They are worth knowing as a pair, because they answer two halves of one question - and because keeping them apart is what stops a block definition turning into a settings screen.

### Presentation variants [#presentation-variants]

How a block looks, as opposed to what it says. A wide hero and a narrow hero used to be either two block types or a `width` field sitting in the middle of the copy. A [variant](/docs/dev/widgets/block-variants) pulls them apart:

```ts
interface BlockInstance {
  data: BlockData
  id: string
  type: string
  variant?: string
}
```

`variant` is optional, and nothing was migrated: an instance stored without one takes the block's `defaultVariant`, exactly as it rendered before. The workaround this replaces - a `variant`, `style` or `size` field declared on the block and stored in `data` - now has a real home, and moving one there is a data migration you write once and never again.

### Layout areas [#layout-areas]

How blocks sit next to each other, which was never one block's business. An [Area](/docs/dev/widgets/layout-areas) is a node in the zone's own list:

```ts
interface BlockAreaInstance {
  children: readonly BlockInstance[]
  id: string
  kind: 'area'
  layout: {
    columns: 1 | 2 | 3 | 4
    gap?: string
    align?: string
    justify?: string
  }
}
```

It is not a block: no registry entry, no `allowedBlocks` entry, no fields of its own. It claims the drop-into gesture that was held back for exactly this, and it stops at one level - **an Area cannot contain an Area** - because nesting needs depth limits, cycle detection and an allowlist story that one level does not.

Three concerns, kept separate: **data** is what the block says, **variant** is how this instance presents it, and **an Area's layout** is how a container arranges its children. Mixing them is what turns a block definition into a settings screen.

## Verifying it yourself [#verifying-it-yourself]

`/example/zones` is the manual test page. It has four zones - two around a locked profile form, one narrower sidebar, one empty - blocks from two plugins, a block stored with a variant, an Area holding two blocks, and a second Area left empty. It draws no button of its own: **Edit widgets** is in the user menu, for anybody holding the page's own moderator permission. It is an [editable page](/docs/dev/widgets/editable-pages), so your changes survive a reload; before anybody saves, it renders the layout the page declares.

Sign in first: the action is gated on the moderator permission **Widgets → can edit** from the example plugin, and a root role holds it without being granted it.

**Load the page**

```bash
pnpm dev
```

Open [http://localhost:3000/example/zones](http://localhost:3000/example/zones) with DevTools → Network open, filtered to **JS**.

</Step>
<Step>

**Confirm no editor chunk was loaded**

Reload and filter the request list to `/src/editor/`. **Nothing.** Not one editor module is requested for a page nobody is editing.

<Callout title="One dev-server caveat" type="warn">
  In this repository you will also see `@dnd-kit` on *every* route, `/`
  included. Those come from the AdminCP dashboard grid, which the development
  module graph reaches whatever page you open - not from the zones. The honest
  measurement is the production build [at the end of this
  page](#against-a-production-build).
</Callout>

</Step>
<Step>

**Open the user menu and click Edit widgets**

It is in the avatar menu in the header, under your name - not on the page. Walk to `/discover` first and look again: it is gone, because no editable page is on screen there.

Click **Finish editing**, then **Edit widgets** again: the second time, **no** request is made. The chunk is already in memory.

</Step>
<Step>

**The sidebar appears on the right**

|        | Expected                                                                                                                                    |
| :----- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| Header | _Available Widgets_.                                                                                                                        |
| Body   | A search field and the installed blocks, grouped by namespace.                                                                              |
| Footer | _No changes yet_, and the Preview, Discard, Save and Finish editing buttons.                                                                |
| Canvas | The page, the header and the footer are all beside the sidebar, not under it. Narrow the window below `md` and the sidebar becomes a sheet. |

</Step>
<Step>

**Search the available widgets**

Type `call` into the search field: the list narrows to `example:callout`. Clear it and everything comes back. Nothing about the page or your changes moves while you search.

</Step>
<Step>

**Drag a block from the sidebar into the empty zone**

`before-footer` is empty, so in edit mode it is a large dashed placeholder. Drag `core:text` from the sidebar onto it.

It lands, it is selected, and the sidebar is already showing its **Properties**.

</Step>
<Step>

**Drag a block between two existing blocks**

Go **← Available Widgets**, then drag `core:cta` over `before-profile` and hover the _top half_ of its second block. A blue insertion line appears above that block; hover the bottom half and it moves below.

Drop on the top half and the new block is second, not last.

</Step>
<Step>

**Move an existing block between compatible zones**

Drag the `core:text` block out of `before-profile` and into `after-profile`. It keeps its content and its instance id - the properties panel does not flicker on the way.

</Step>
<Step>

**Move a block with the keyboard only**

Put the mouse down. <kbd>Tab</kbd> to a block, press <kbd>Space</kbd>, then <kbd>↓</kbd>.

The blue insertion line appears under the block below, exactly as it does for a pointer - keep pressing <kbd>↓</kbd> and it walks into the next zone. <kbd>Space</kbd> drops the block where the line is; <kbd>Esc</kbd> puts it back. Whatever the line said, that is where the block lands.

</Step>
<Step>

**Watch an incompatible zone refuse**

Drag `example:callout` - from the sidebar, or from a zone that holds one - toward `sidebar`, which allows `core:text` only.

The zone turns red and says it does not accept the block. Release: nothing moves and nothing is inserted. Now press **Add block** inside that sidebar zone and confirm the catalogue offers `core:text` and nothing else.

</Step>
<Step>

**Select a block**

Click any block on the page. Expect a ring around it and a floating row of actions - Edit, Delete - in its corner.

</Step>
<Step>

**The sidebar switches to Properties**

Same panel, different mode. Expect the block's name, its type underneath, its fields, a Duplicate and a Delete at the bottom, and a **← Available Widgets** at the top.

</Step>
<Step>

**Edit a field**

Type into the heading or body field of the selected block.

</Step>
<Step>

**The block updates immediately**

The block on the page changes **while you type** - no Apply button, no delay - and the sidebar footer switches to _Unsaved changes_.

</Step>
<Step>

**Go back to Available Widgets**

Press **← Available Widgets**. The catalogue returns and the ring on the page disappears, because that action clears the selection as well as the panel.

</Step>
<Step>

**Switch a variant**

Select the `example:features` block in `before-profile`. Above its fields sits a **Variant** picker holding _Grid_, _List_ and _Compact_.

Move through all three. The block re-renders each time, and every word in the fields underneath stays exactly as it was - the variant is not content, so nothing about the content is touched. The footer says _Unsaved changes_, because the page did change.

</Step>
<Step>

**Add an Area, and move blocks in and out of it**

Go **← Available Widgets**. Above the plugin groups is a **Layout** section holding one entry: **Area**. Click it - an empty two-column Area lands in the page.

Now drag a root block onto it: it becomes a child, and the Area re-flows around it. Drag it back out to the zone and the Area keeps the rest. Reorder two children inside one Area and only their order changes. Try to drag an Area onto another Area: it is refused, out loud.

</Step>
<Step>

**Area properties**

Click the Area's own shell rather than one of its children. The sidebar shows **Area properties**: Columns, Gap, the space above/below and left/right, Alignment and Distribution - each re-laying the page out as you pick it - with **Duplicate area**, **Ungroup** and **Delete area** under them.

Gap and the two spacing controls are sliders measured in **pixels, 0 to 100**. Dragging one moves the page under the thumb. Gap is the room between the Area's own children; the other two are its outer margin, stored beside its columns as `marginX` and `marginY`. Pixels a person picked are not design tokens, so all three are written as an inline `style` rather than a utility class - and an Area asking for no margin renders exactly the markup Areas always have, so nothing on an existing page moves.

An Area laid out before this - one storing `gap: "md"` rather than `gap: 16` - still reads. Every door into a layout resolves the old names (`none` 0, `sm` 8, `md` 16, `lg` 32) to their number, and the next save writes the number down, so nothing has to migrate the table.

An empty Area draws one **Drop widgets here** cell per column, so a four-column Area shows the four places a widget can go before anything is in it.

Press **Ungroup**: the container goes and its blocks stay, at the position the Area held. Undo that by adding an Area back and filling it, then press **Delete area**: it asks first, and offers _Ungroup, keep widgets_ in the same dialog. Delete the empty Area the page ships with and it does not interrogate you - there is nothing inside to lose.

</Step>
<Step>

**Preview**

Press **Preview**. Outlines, handles and overlays go; the sidebar collapses to a slim bar with **Back to editing** and **Finish editing**. Click a link inside a block - it works now, because the `inert` wrapper is gone.

**Back to editing** restores everything, unsaved changes included.

</Step>
<Step>

**Save**

Press **Save** in the sidebar footer - not the profile form's own Save button, which is there to prove the form still works.

|         | Expected                                                                                                                                                                  |
| :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Toast   | _Page saved_.                                                                                                                                                             |
| Footer  | Switches from _Unsaved changes_ to _Saved_.                                                                                                                               |
| Header  | The line under the title stops saying the page ships these widgets and names the time it was rearranged.                                                                  |
| Payload | A **Last save payload** block appears at the bottom of the page - open it and read the JSON that went to `PUT /pages/layout`. Edit one zone and it names that zone alone. |

Check that `changedZoneIds` lists only the zones you actually touched.

</Step>
<Step>

**Finish editing, without reloading**

Press **Finish editing**. The public page is back: no outlines, no sidebar, and `before-footer` is invisible again if you left it empty.

The part worth checking is that **the page you are looking at is the page you saved** - the block you added, the one you moved and the text you typed, all in view mode, with no refresh anywhere. Then reload, and confirm you get the same thing a second time. The first comes from the API's answer to the save; the second from the route loader.

Now do it the other way round: click **Edit widgets**, change something, and press **Finish editing** without saving. The dialog offers **Save and finish**, **Leave without saving** and **Keep editing** - and note that **Save** on its own, back in the footer, would have kept you in edit mode instead.

</Step>
</Steps>

### While you are in there [#while-you-are-in-there]

- **Nothing on the page restarts.** Type a name into the profile form, press the **Local state** counter a few times, then **Edit widgets** and **Finish editing**. Both survive, both directions, because the editor mounts beside your page rather than around it.
- **Take the sidebar zone off the page** with the button above the zones, while the editor is open. It leaves the editor with it: the outline goes, an **Add widget** target pointing at it clears, and a selected block inside it returns the sidebar to _Available Widgets_. Save afterwards and the stored sidebar keeps what it had - the editor's copy is not written back, and it is not reset to defaults either. Edit it first and the footer names it rather than losing the change quietly. Put it back and it returns with a fresh baseline.
- **Discard** puts every zone back to what loaded, and the footer stops saying _Unsaved changes_.
- **An empty Area is edit-mode only.** The page ships one. In edit mode it is a two-column drop target; press **Finish editing** and it leaves no markup behind at all, exactly like an empty zone.
- **Add widget inside an Area** targets the Area, not the zone: the sidebar header reads _For: an area in after-profile_, and the **Layout** section disappears while it does, because an Area cannot hold another Area.
- **Duplicate** drops a copy directly below the original with its own instance id; **Delete** takes it away and returns the sidebar to the catalogue.
- The profile form in the middle must have **no** outline, **no** drag surface and **no** overlay, and its input must still take focus and type. It is application code.
- Navigating away with unsaved changes - a header link, or the back button - prompts, with **Keep editing** and **Leave without saving**.
- **Below `md`** the sidebar becomes a bottom sheet and the canvas gains padding to match: scroll to the end and the last zone, its **Add widget** button included, clears the sheet completely. **Preview** takes the padding away with the sheet, so the page is exactly as a visitor sees it.
- **Seed something unreadable** and the refusal is easy to see. Save the zone once first, so there is a row to corrupt:

```bash
  psql "$POSTGRES_URL" -c 'update core_page_layouts set "zones" = \'{"before-profile":[{"foo":"bar"}]}\' where "pageId" = \'example:settings\';'
  ```

Reload, press **Edit widgets**: `before-profile` shows _This zone holds content the editor cannot read_ with `{"foo":"bar"}` printed under it, **Save** is disabled whatever else you change, and the footer says why. Press **Remove invalid entry**, and Save comes back. **Discard** puts it straight back.

### Against a production build [#against-a-production-build]

```bash
pnpm build
pnpm start
```

Then confirm the editor never reached a visitor:

```bash
curl -s http://localhost:3000/example/zones | grep -cE 'dnd-kit|editor/root'
```

`0`. The [boundary test](#the-lazy-loading-guarantee) is the standing guarantee; this is the spot check that the guarantee survived bundling.

# Email Verification (/docs/dev/working-with-users/email-verification)

When your install has an [email adapter](/docs/dev/email), every new member has to click a confirmation link before they can sign in. Without one, there is nobody to send the link, so accounts are confirmed the moment they are created and nothing changes.

That stops the oldest trick in the book: signing up with somebody else's address and using the account straight away.

## What a member sees [#what-a-member-sees]

1. They register at `/register`. Instead of being signed in, they get a "Check your email" card.
2. The email holds a link to `/login/verify-email?token=...`, valid for **24 hours**.
3. That page asks them to click **Confirm email address**. The page never confirms on load, because mail scanners and link previews open every URL in an email.
4. Once confirmed, they sign in with their password as usual.

If they try to sign in first, the sign-in form says **Confirm your email first** and offers **Send a new confirmation link**, which opens the resend form with their address already filled in.

<Callout type="info" title="The password comes first">
  The "not confirmed" message only appears after the password has been checked.
  A wrong password, an unknown address and an unconfirmed account with a wrong
  password all get the same `403`, so the sign-in form can't be used to find out
  which addresses are registered.
</Callout>

## The rules [#the-rules]

- **Password sign-in** answers `403 { "error": "email_not_verified" }` for an unconfirmed account. No session is created.
- **Passkey sign-in** follows the same rule, with the same error code.
- **AdminCP sign-in** at `/admin` is not blocked. Only staff get in, and staff are picked by an administrator, so an install that just added an email adapter can't lock its admins out.
- **SSO** sign-ups are confirmed already, since the provider vouches for the address.
- **Completing a password reset** also confirms the address - the reset link went to the same mailbox.
- **Staff** can confirm anyone by hand from the AdminCP user page.

<Callout type="warn" title="Adding an email adapter to an existing install">
  Members who registered while an adapter was configured but before this feature
  existed were never sent a link, so they are still unconfirmed. They can use
  **Send a new confirmation link** on the sign-in form, reset their password, or
  a staff member can confirm them from the AdminCP.
</Callout>

## API routes [#api-routes]

All routes live under `/api/@vitnode/core/users`.

| Method | Path                   | Body                      | Answers                                                     |
| :----- | :--------------------- | :------------------------ | :---------------------------------------------------------- |
| `POST` | `/verify-email`        | `{ token }`               | `200 { email }`, or `400` for a wrong, used or expired link |
| `POST` | `/verify-email/resend` | `{ email }`, plus captcha | `201` for every address; `404` with no email adapter        |

`/verify-email/resend` answers the same `201` for an unknown address, a confirmed one and one waiting for confirmation, so it can't be used to check who has an account. It only sends when the account still needs confirming, and only once every five minutes. A new link replaces the old one.

Call them through the [fetcher](/docs/dev/fetcher) like any other core route:

```ts title="src/lib/confirm-email.ts"
import { fetcher } from '@vitnode/core/tanstack/fetcher'

const response = await fetcher({
  plugin: '@vitnode/core',
  method: 'post',
  module: 'users',
  path: '/verify-email',
  args: { body: { token } },
})
```

Confirming a link does not sign anybody in. Whoever clicks it owns the mailbox, but not necessarily the account - if a stranger registered with your address, your click must not drop you into their session.

## How links are stored [#how-links-are-stored]

Links live in `core_users_confirm_emails`, one row per account:

- The token is 32 random bytes, base64url-encoded. Only its SHA-256 digest is stored, so a leaked database dump can't confirm anything.
- A link works once. Spending it deletes the row in the same statement that reads it, so two clicks racing each other can't both win.
- The hourly `clean` [cron job](/docs/dev/cron) deletes expired rows.

## Events [#events]

Confirming an address emits `user.email.verified` with `{ userId, email }` - from the link, from a completed password reset, or from staff in the AdminCP. See [built-in events](/docs/dev/events/built-in-events).

# Roles (/docs/dev/working-with-users/roles)

In VitNode, a role groups users together for display styles (e.g. colored username badges) and staff permission grants.

## Quick start [#quick-start]

Resolve a user's complete set of role IDs (primary + secondary) on the API:

```ts
import { getUserRoleIds } from '@vitnode/core/api/lib/check-staff-permission'

const user = c.get('user')
// [!code ++:1]
const roleIds = user ? await getUserRoleIds(c, user) : []
```

---

## Seeded Default Roles [#seeded-default-roles]

VitNode automatically seeds four protected system roles upon installation:

<Callout type="info" title="First Account is Root">
  The first user to register during site initialization is automatically
  assigned the Administrator role.
</Callout>

---

## Role Model Attributes [#role-model-attributes]

`core_roles` defines group styling and properties:

- `color`: CSS color string (e.g. `#ff0000`, `hsl(210, 100%, 50%)`) applied to member usernames across the UI.
- `prefix`: An emoji or a Lucide icon rendered in front of the role name and in front of every member's username. Stored as `emoji:🚀` or `icon:rocket` - see the [Emoji & Icon Picker](/docs/ui/emoji-icon-picker) for the codec and the components that read it.
- `root`: When `true`, user bypasses all staff permission checks.
- `default`: The role automatically assigned to newly registered members.
- `guest`: Reserved for unauthenticated requests.

---

## Primary vs Secondary Roles [#primary-vs-secondary-roles]

Every user has exactly one **primary role** (stored in `core_users.roleId`). Users may additionally hold multiple **secondary roles** (stored in `core_users_secondary_roles`), inheriting combined staff permissions across all assigned groups.

---

## AdminCP Role Management [#admincp-role-management]

{/* Image prompt: VitNode AdminCP Roles management page at /admin/core/roles. Table showing custom roles with colored name badges, member counts, and action buttons to reorder, edit, or delete roles. Dark theme, 1440x900. */}

Create, color-code, and organize user groups under **Core → Roles** (`/admin/core/roles`).

The **General** tab of the create/edit dialog carries both display fields: **Color**, which tints member usernames, and **Prefix**, which puts an emoji or an icon in front of them.

## Learn More [#learn-more]

# Staff Permissions (/docs/dev/working-with-users/staff-permissions)

VitNode separates staff into two groups: **Moderators** and **Administrators**. Plugins declare granular permissions that restrict what staff members or roles can access.

<Callout type="warn" title="New Admin APIs Require Staff Permissions">
  Routes under `/admin/` are automatically gated by the admin session, but you must declare an explicit staff permission tuple to restrict specific actions.
</Callout>

## Quick start [#quick-start]

### 1. Declare Permissions in Plugin API Config [#1-declare-permissions-in-plugin-api-config]

```ts title="plugins/blog/src/config.api.ts"
import { buildApiPlugin } from "@vitnode/core/api/lib/plugin"

export const blogApiPlugin = () =>
  buildApiPlugin({
    pluginId: "@vitnode/blog",
    // [!code ++:8]
    permissionStaff: {
      admin: {
        posts: [
          "can_view",
          { permission: "can_delete", dependsOn: ["can_view"] },
        ],
      },
    },
  })
```

### 2. Enforce on Hono Route [#2-enforce-on-hono-route]

Add `adminStaffPermission` to automatically return `403 Forbidden` if unauthorized:

```ts title="plugins/blog/src/api/modules/admin/posts/routes/delete.route.ts"
export const deletePostRoute = buildRoute({
  pluginId: "@vitnode/blog",
  // [!code ++:1]
  adminStaffPermission: { module: "posts", permission: "can_delete" },
  route: {
    method: "delete",
    path: "/{id}",
    responses: {
      200: { description: "Post deleted" },
      403: { description: "Forbidden" },
    },
  },
  handler: async (c) => {
    // Execution only reaches here if caller has permission
  },
})
```

---

## Add Permissions Step by Step [#add-permissions-step-by-step]

### 1. Define Translation Labels [#1-define-translation-labels]

Add flat labels in `plugins/blog/src/locales/en.json`:

```json title="plugins/blog/src/locales/en.json"
{
  "@vitnode/blog": { "title": "Blog" },
  "@vitnode/blog:posts": "Articles",
  "@vitnode/blog:posts:can_view": "View articles list",
  "@vitnode/blog:posts:can_create": "Create articles",
  "@vitnode/blog:posts:can_delete": "Delete articles"
}
```

</Step>
<Step>

### 2. Gate UI Controls [#2-gate-ui-controls]

Hide buttons or panels from unauthorized staff with `AdminStaffPermissionGate`:

```tsx title="plugins/blog/src/admin/delete-post-button.tsx"
import { AdminStaffPermissionGate } from "@vitnode/core/components/staff-permission/provider"

export const DeletePostButton = () => (
  // [!code ++:5]
  <AdminStaffPermissionGate
    plugin="@vitnode/blog"
    module="posts"
    permission="can_delete"
  >
    <button className="text-destructive">Delete</button>
  </AdminStaffPermissionGate>
)
```

Or check permissions imperatively with `useStaffPermissions`:

```tsx
const { hasPermission } = useStaffPermissions()
const canDelete = hasPermission({ module: "posts", permission: "can_delete" })
```

</Step>
<Step>

### 3. Gate Sidebar Navigation [#3-gate-sidebar-navigation]

Attach `permission` to navigation items in `src/admin/nav.tsx`:

```tsx title="plugins/blog/src/admin/nav.tsx"
export const adminNav: PluginAdminNav = {
  nav: [
    {
      id: "posts",
      href: "/admin/blog/posts",
      icon: <ListIcon />,
      permission: { module: "posts", permission: "can_view" }, // [!code ++]
    },
  ],
}
```

</Step>
<Step>

### 4. Grant Permissions in AdminCP [#4-grant-permissions-in-admincp]

{/* Image prompt: VitNode AdminCP staff permission editor at /admin/core/staff/admins. Left sidebar lists plugins (Core, Blog). Right panel displays permission toggles grouped by module ("Articles") with dependency locks and an Unrestricted / Restricted level switcher. Dark theme, 1440x900. */}

1. Go to **Staff → Administrators** (`/admin/core/staff/admins`).
2. Select a User or Role and click **Edit**.
3. Choose **Restricted**, toggle the desired permissions, and click **Save Changes**.

</Step>
</Steps>

---

## Permission Dependencies [#permission-dependencies]

When a permission depends on another (e.g. creating posts requires viewing them), declare `dependsOn`:

```ts title="plugins/blog/src/config.api.ts"
permissionStaff: {
  admin: {
    posts: [
      "can_view",
      { permission: "can_create", dependsOn: ["can_view"] },
      { permission: "can_delete", dependsOn: ["can_view"] },
    ],
  },
}
```

The AdminCP permission editor automatically disables child toggles until prerequisites are checked.

## Moderator permissions with scopes [#moderator-permissions-with-scopes]

A moderator permission can be limited to some resources of a scope family, such as some forum sections. Declare the family with `scope` on the entry:

```ts title="config.api.ts"
permissionStaff: {
  moderator: {
    topics: [
      { permission: "can_view_reports", scope: "forum.section" },
      {
        permission: "can_manage_reports",
        dependsOn: ["can_view_reports"],
        scope: "forum.section",
      },
    ],
  },
},
```

Each grant then carries a scope, and dependencies are checked per resource: managing in a section needs viewing in that section. The scope families and the AdminCP picker are covered in [Scoped moderator permissions](/docs/dev/moderation/scoped-permissions).

## Learn More [#learn-more]

# Users & Sessions (/docs/dev/working-with-users/users)

Every incoming request in VitNode resolves the session cookie prior to route execution. The current user profile is accessible on both server handlers and frontend components.

## Quick start [#quick-start]

### 1. In Hono API Routes [#1-in-hono-api-routes]

Access the authenticated user via `c.get("user")`:

```ts title="plugins/blog/src/api/modules/posts/routes/create.route.ts"
import { HTTPException } from 'hono/http-exception'

handler: async (c) => {
  // [!code ++:4]
  const user = c.get('user')
  if (!user) {
    throw new HTTPException(401, { message: 'Unauthorized' })
  }

const newPost = await createPost({ authorId: user.id })
  return c.json(newPost)
}
```

---

### 2. In Frontend Components [#2-in-frontend-components]

Consume the user session via TanStack Query:

```tsx title="src/components/user-greeting.tsx"
import { useSessionQuery } from '@vitnode/core/tanstack/auth'

export const UserGreeting = () => {
  // [!code ++:2]
  const { data } = useSessionQuery()
  const user = data?.user

if (!user) return <span>Welcome, guest!</span>

return <span>Welcome back, {user.name}!</span>
}
```

`useSessionQuery()` wraps `useQuery(sessionQueryOptions())`, so it never
suspends: `data` is `undefined` on the very first render of a page that did not
warm it in a loader. Routes that want the session ready before paint call
`ensureAuthState(queryClient)` in their loader.

---

### 3. In the AdminCP [#3-in-the-admincp]

The AdminCP session is a **second cookie**, and a second query. `isAdmin` on the
public session means "may be offered the AdminCP", not "is inside it" - so an
admin screen never answers an admin question with the public session.

```tsx title="plugins/blog/src/admin/current-admin.tsx"
import { useAdminSessionQuery } from '@vitnode/core/tanstack/admin'

export const CurrentAdmin = () => {
  // [!code ++:1]
  const { data } = useAdminSessionQuery()

if (data.status !== 'granted') return null

return <span>Signed in as {data.session.user.name}</span>
}
```

`useAdminSessionQuery()` wraps `useSuspenseQuery(adminSessionQueryOptions())`,
so `data` is always there and the screen suspends instead of rendering an empty
state. The AdminCP layout warms it, which is why every screen below it reads a
cache hit. Two shorthands sit on top of it:

---

## User Model (`core_users`) [#user-model-core_users]

The canonical user table contains:

Every user payload the API hands out - the session, the public profile, the
AdminCP list and detail, search hit authors - carries the two images resolved
to URLs as `avatarUrl` and `coverUrl`. Both are `null` until something is
uploaded, and the `Avatar` component falls back to the letter avatar on its own -
drawn from the first character of `nameCode`, never of the displayed name, so a
member who changes which name their profile shows keeps the same face in every
list they appear in.

### Personal information [#personal-information]

`firstName`, `lastName`, `phone` and `headline` are the user's own to set, at **Settings →
Overview** (`/settings`). The Profile card lists them read-only; **Edit profile**
opens one sheet with every field, the **Show my real name** switch and the time
zone, so changing three things takes one save instead of three. Every field is
optional, stored as `null` rather than an empty string when cleared, and the
session payload carries them so anything already reading the session can show
them without a second request.

| Method  | Path                                 | Who                                  |
| :------ | :----------------------------------- | :----------------------------------- |
| `GET`   | `/api/@vitnode/core/users/me/policy` | The signed-in user - may they edit?  |
| `PATCH` | `/api/@vitnode/core/users/me`        | The signed-in user, on their own row |

The body takes any subset of
`{ firstName, lastName, phone, headline, showRealName }` -
a field left out is left alone, and a text field sent as `""` or whitespace is
cleared. Writing invalidates the user's cached session and emits
[`user.updated`](/docs/dev/events/built-in-events).

`phone` is the one field with a shape: digits and the punctuation international
numbers are written with (`+`, spaces, `-`, `(` and `)`), up to 32 characters.
Anything else is rejected by the form and by the route. It is **not** on the
public profile payload - only the account's own session carries it.

### Time zone [#time-zone]

`timeZone` sits under **Region** in the same **Edit profile** sheet. It takes any
IANA name, like `Europe/Warsaw`, and **Use this device's time zone** fills the
field from the browser in one click - it still waits for **Save changes**. `null` means "follow my language", then UTC.
Notification digests go out in this time zone, and the session carries it, so
`c.get("user")?.timeZone` is there for anything else that wants local time.

| Method | Path                                    | Who                                  |
| :----- | :-------------------------------------- | :----------------------------------- |
| `PUT`  | `/api/@vitnode/core/users/me/time-zone` | The signed-in user, on their own row |

The body is `{ timeZone: string | null }`. An unknown name answers `400`.
Saving invalidates the cached session and emits
[`user.updated`](/docs/dev/events/built-in-events).

### Which name the public sees [#which-name-the-public-sees]

`showRealName` decides whether a profile is headed by the nickname (`name`) or by
`firstName lastName`. The public profile route resolves it **server-side** and
returns the answer as `name`, so a real name the user has not published never
leaves the API. When the switch is on but neither half is set, the nickname is
used, so turning it on early cannot leave a profile with an empty heading.

The AdminCP and search always show `name`, the account's own nickname - staff
need the identifier the account is filed under.

### What the profile header shows [#what-the-profile-header-shows]

{/* Image prompt: VitNode public profile header at /users/aXen. Wide cover image with a rounded-square avatar overlapping its bottom-left corner, the display name and @nameCode beside it, and a single row of muted meta items with small icons - a briefcase for the headline, a shield for the primary role, a calendar for the join date - with an "Edit profile" outline button at the far right. Light theme, 1440x400. */}

`GET /api/@vitnode/core/users/profile/{nameCode}` answers with the header's whole
payload: `name` (already resolved), `nameCode`, `headline`, `avatarUrl`,
`coverUrl`, `avatarColor`, `createdAt`, the primary `role` and any
`secondaryRoles`. The header draws the headline, the role and the join date as
one row of meta items, each with its own icon, and stacks them centred under the
avatar on a phone.

`headline` follows the install switch: with `users.personalInformation.headline`
set to `false` the route returns `null` for everyone, so turning the field off
takes it off public profiles too, without touching what members had written.

The **Edit profile** button is the header's action slot. It is rendered only for
the account's own profile; a host that renders `ProfileContent` itself can pass
any `action` it likes - a follow button, a "message" link, nothing at all.

### Who may edit it [#who-may-edit-it]

Each role has **Allow editing personal information** on its **Profile** tab
(`allowEditPersonalInfo`, default `true`). A user may edit only when **every**
role they hold allows it - one role that switches it off is enough to lock the
card.

That is the opposite of the image allowances, which grant on _any_ role, and
deliberately so: this column defaults to `true`, so under "any role grants" an
administrator who switched it off on one role would find it silently re-granted
by every other role the member happens to hold, and the setting would almost
never take effect.

The **Edit profile** sheet then shows only the time zone, which every member may
change, and `PATCH /users/me` answers `403` regardless of what the UI showed.

### Turning fields off for the whole install [#turning-fields-off-for-the-whole-install]

Roles decide _who_ may edit. The API config decides _which fields exist at all_.
Every field is on unless you set it to `false` in `vitnode.api.config.ts`:

```ts title="vitnode.api.config.ts"
export const vitNodeApiConfig = buildApiConfig({
  // ...
  users: {
    personalInformation: {
      phone: false,
      headline: false,
      showRealName: false,
    },
  },
})
```

The keys are `firstName`, `lastName`, `phone`, `headline` and `showRealName`. A
field switched off disappears from the settings card and from its form, and
`PATCH /users/me` refuses to write it even if a caller sends it anyway - so a
stale browser tab or a hand-rolled request cannot get around it.

Switching a field off never deletes anything: the column keeps whatever members
had already set, so turning it back on restores their values. With
`showRealName` off, every profile is headed by the nickname again, whatever
individual members had chosen. With **every** field off there is nothing left to
edit, so the **Edit** button disappears too.

---

## AdminCP User Management [#admincp-user-management]

{/* Image prompt: VitNode AdminCP User management screen at /admin/core/users. Data table listing registered accounts with columns for Avatar, Name, Email, Primary Role badge, Status, and action dropdowns (Edit, Ban, Delete). Dark theme, 1440x900. */}

Administrators can view, edit, ban, and assign roles to users at **Core → Users** (`/admin/core/users`).

---

### Edit a user [#edit-a-user]

{/* Image prompt: VitNode AdminCP user page at /admin/core/users/1. Left column: profile card with cover, round avatar, name, @handle, Staff and Verified badges, then Personal information, Preferences, Roles, Connected accounts and Devices cards. Right column: segmented tabs Activity, Notifications, Password & passkeys above a vertical activity timeline. Dark theme, 1440x1000. */}

Open a user at `/admin/core/users/[id]`. Everything the member can change in their own `/settings` is editable here too.

A few rules differ from the member's own settings:

- **Staff can edit locked fields.** The role's **Allow editing personal information** and the install's `users.personalInformation` switches limit members, not staff.
- **Notification locks still apply.** Mandatory types, and types the notification settings stop members from changing, are read-only here too, because delivery ignores stored choices for them.
- **The last sign-in method can't be removed.** Disconnecting the only SSO account or deleting the only passkey answers `409`.
- **Setting a password signs the member out everywhere**, AdminCP sessions included.
- **Sync now isn't offered.** It needs the member to sign in with the provider themselves.

Every write needs `users:can_edit`, plus `users:can_edit_admin` when the target is staff. Reads need `users:can_view`.

| Method   | Path                                                                | Does                                                 |
| :------- | :------------------------------------------------------------------ | :--------------------------------------------------- |
| `PATCH`  | `/api/@vitnode/core/admin/users/{id}`                               | Account, personal information and preferences        |
| `PUT`    | `/api/@vitnode/core/admin/users/{id}/password`                      | Sets a new password and revokes every session        |
| `GET`    | `/api/@vitnode/core/admin/users/{id}/devices`                       | Devices with an active session                       |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/devices/{publicId}`            | Signs one device out                                 |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/devices`                       | Signs every device out                               |
| `GET`    | `/api/@vitnode/core/admin/users/{id}/passkeys`                      | Passkeys                                             |
| `PATCH`  | `/api/@vitnode/core/admin/users/{id}/passkeys/{passkeyId}`          | Renames a passkey                                    |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/passkeys/{passkeyId}`          | Deletes a passkey                                    |
| `GET`    | `/api/@vitnode/core/admin/users/{id}/sso`                           | Connected accounts, sign-in summary, profile sources |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/sso/{providerId}`              | Disconnects an account                               |
| `PUT`    | `/api/@vitnode/core/admin/users/{id}/sso/preferences`               | Profile sources and sync on sign-in                  |
| `GET`    | `/api/@vitnode/core/admin/users/{id}/notification-preferences`      | Notification preferences per type                    |
| `PUT`    | `/api/@vitnode/core/admin/users/{id}/notification-preferences`      | Changes notification preferences                     |

The `PATCH` body takes any of `email`, `name`, `nameCode`, `roleId`, `secondaryRoleIds`, `firstName`, `lastName`, `headline`, `phone`, `showRealName`, `birthday` (`YYYY-MM-DD` or `null`), `language`, `timeZone` (`null` for automatic) and `newsletter`. At least one field is required.

---

### Where it happens [#where-it-happens]

- **Profile page** (`/users/[nameCode]`): the owner sees a camera button on the
  cover and on the avatar. It opens one dialog that both uploads and removes:
  with a picture already set, a pair of radio buttons chooses between them and
  the confirm button reads **Upload** or **Delete** to match; with nothing set
  yet, the dialog goes straight to the picker.
- **Settings overview** (`/settings`): the avatar and its camera button only,
  beside the name, code name, role and email the account carries, above the
  personal information the user sets for themselves. The cover is
  edited on the profile page.
- **AdminCP** (`/admin/core/users/[id]`): the same two buttons and the same
  dialog, for anybody holding `users:can_edit` - plus `users:can_edit_admin`
  when the target is an administrator. Staff can always set an image, even when
  the user's own roles cannot; the role's size cap still applies.

### Role settings [#role-settings]

Each role decides, on its **Profile** tab at **Core → Users → Roles**:

A user with several roles is allowed as soon as **one** of them allows the
image, and gets the **most generous** cap among those roles. The cap is shown in
the dialog before a file is picked, and checked again on the server.

### API [#api]

| Method   | Path                                                | Who                                                              |
| :------- | :-------------------------------------------------- | :--------------------------------------------------------------- |
| `GET`    | `/api/@vitnode/core/users/images/policy`            | Signed-in user - what they may upload, and the caps in bytes     |
| `POST`   | `/api/@vitnode/core/users/images/{kind}`            | Signed-in user - multipart `file`, `kind` is `avatar` or `cover` |
| `DELETE` | `/api/@vitnode/core/users/images/{kind}`            | Signed-in user                                                   |
| `POST`   | `/api/@vitnode/core/admin/users/{id}/images/{kind}` | Staff with `users:can_edit`                                      |
| `DELETE` | `/api/@vitnode/core/admin/users/{id}/images/{kind}` | Staff with `users:can_edit`                                      |

Accepted types are JPEG, PNG and WebP. The browser crops to `512×512` for an
avatar and `1800×600` for a cover and sends WebP where the browser can encode
it, so uploads are usually far under the cap. A refused upload answers `400`
with `{ error }` written for the person who picked the file, and a role that
does not allow the image answers `403`.

Both writes emit an event -
[`user.avatar.updated` and `user.cover.updated`](/docs/dev/events/built-in-events)

- with the new `core_files` id, or `null` when the image was removed.

## Learn More [#learn-more]

# Install the Blog Plugin (/docs/guides/blog)

`@vitnode/blog` is the Content Engine reference plugin. It brings articles,
categories, editorial screens, revisions, public delivery data, and search
indexing—without making your host app impersonate a blog plugin.

### Install the package [#install-the-package]

```bash tab="bun"
bun add @vitnode/blog@canary
```

```bash tab="pnpm"
pnpm add @vitnode/blog@canary
```

```bash tab="npm"
npm install @vitnode/blog@canary
```

</Tabs>

</Step>
  <Step>

### Enable the API plugin [#enable-the-api-plugin]

For a Single App, edit `apps/web/src/vitnode.api.config.ts`; a split deployment
uses the same change in `apps/api/src/vitnode.api.config.ts`.

```ts title="apps/web/src/vitnode.api.config.ts"
import { blogApiPlugin } from '@vitnode/blog/config.api' // [!code ++]

export const vitNodeApiConfig = buildApiConfig({
  plugins: [
    blogApiPlugin(), // [!code ++]
  ],
})
```

</Step>
  <Step>

### Enable the web plugin [#enable-the-web-plugin]

One line, and it brings the blog's pages, its AdminCP screens and its
translations with it - your build reads the factory and writes the loaders into
`src/package-messages.gen.ts` for you:

```ts title="apps/web/src/vitnode.config.ts"
import { blogPlugin } from '@vitnode/blog/config' // [!code ++]

export const vitNodeConfig = buildConfig({
  plugins: [
    blogPlugin(), // [!code ++]
  ],
})
```

</Step>
  <Step>

### Migrate, run, and publish [#migrate-run-and-publish]

```bash tab="bun"
bun run db:migrate
bun dev
```

```bash tab="pnpm"
pnpm db:migrate
pnpm dev
```

```bash tab="npm"
npm run db:migrate
npm run dev
```

</Tabs>

In AdminCP, create a category at **Blog → Categories**, then publish an article
at **Blog → Articles**. The plugin owns the editorial work so the host can stay
boringly reliable.

{/* Image prompt: VitNode AdminCP Blog article management screen. Show categories in a side navigation, article list with draft and published badges, and a prominent “Create article” button. Dark theme, 1440x900. */}

</Step>
</Steps>

## Write and translate articles [#write-and-translate-articles]

The article editor reads top to bottom like the published article: the cover
image and its alt text, then the title, slug and content. The checks before
publishing live in the **SEO** sheet, so the text gets the whole width.

{/* Image prompt: VitNode AdminCP blog article editor at full width. A wide cover image with Replace file and Remove buttons in its corner, alt text field under it, a large article title and slug, then a TipTap editor. Header with Translate, SEO with a small amber badge "2", AI review, a muted "● Published" label and a split Save changes button with a dropdown arrow. Light theme, 1440x900. */}

### Check the article before you publish [#check-the-article-before-you-publish]

Press **SEO** in the header to open the **Ready to publish** sheet. The badge on
the button counts what is still left, so you know when it needs a look. The
sheet checks what a published article usually needs:

| Check                            | Passes when                                                 |
| -------------------------------- | ----------------------------------------------------------- |
| Title fits search results        | Every started language has a title of 60 characters or less |
| Excerpt in every language        | Every started language has an excerpt                       |
| Cover image                      | A cover image is set                                        |
| URL                              | The language you edit has a friendly URL                    |
| Cover alt text in every language | Every started language describes the cover                  |
| Translations complete            | Every language has a title, friendly URL and content        |
| Translations up to date          | No translation is older than the default language           |

The title, excerpt and alt text fields show a live counter against the
recommended length: 60, 160 and 125 characters. They are recommendations, not
limits, so you can still save a longer title.

Each row is green when it is done and says what is missing when it is not, and
the bar on top counts how many are ready. You can fix most rows right there:
write the excerpt in its row, press **Edit under the cover** to jump to the alt
text, or **Open** a language that is missing a translation.

### Publish or unpublish [#publish-or-unpublish]

The header shows whether the article is a **Draft** or **Published** (hover it
to see when it went live). To change that, open the arrow next to **Save
changes** and pick **Publish** or **Unpublish**. It asks for confirmation
first, because readers see the change immediately. **Hide** and **Unhide** live
in the same menu.

### Hide or duplicate an article [#hide-or-duplicate-an-article]

The **More actions** menu of an article in the list has **Hide** and
**Duplicate**. Hiding takes a published article off the site, search and the
sitemap without unpublishing it, and **Unhide** brings it back with the same
URL and date. It needs the **Hide and unhide articles** permission. Duplicating
makes a draft copy with every translation, such as "Hello world (Copy)". See
[Hide content](/docs/content-engine/content-visibility) and
[Duplicate content](/docs/content-engine/duplicate-content).

### Translate side by side [#translate-side-by-side]

Pick a language from **Translate**. Each translated field then shows the default
language on the left, read-only, and the language you translate into on the
right. Your shared fields, such as categories and authors, stay in one place.

A translation is marked **outdated** when the default language was saved after
it. **Generate from title** builds the friendly URL from the translated title.

### Use AI helpers [#use-ai-helpers]

With AI configured, the editor adds:

- **Translate** on each field, and **Translate missing fields** for a whole
  language. Content keeps its formatting.
- **Write with AI** on the excerpt, which writes it from the title and content.
- **AI review** in the header, which opens a sheet with suggestions about
  clarity, completeness, structure and tone. When a suggestion is about the
  wording, **Show fix** shows the current text next to a rewrite, and **Apply**
  puts the rewrite into the article. **Dismiss** hides a suggestion you do not
  agree with. The review never blocks publishing.

<Callout type="info" title="When the AI buttons appear">
  The buttons appear only when the API has at least one model in `ai.models`.
  The routes behind them require the `can_edit` permission on articles. See
  [AI](/docs/dev/ai) to configure a model.
</Callout>

AI never saves for you. Read the suggestion, then press **Save changes**.
While others are editing the article, a translated body goes into the shared
editor as one change, so everyone sees it and you can undo it.

### Write together [#write-together]

Several people can work on one article at once. The header shows who else is
in it, and a colored outline with a name tag shows who is editing which field. The title,
slug, excerpt and other plain fields are edited by one person at a time; the
article body is shared, with everyone's cursor visible. Your changes are
autosaved to a draft until someone presses **Save changes**. See
[Live editing and autosave](/docs/content-engine/live-editing) for how it
works and what it needs on your server.

### Upgrade an existing blog [#upgrade-an-existing-blog]

Articles have a localized **Excerpt** field. Search results use it as the
description and fall back to the article content when it is empty. The article
content is now stored as [rich text](/docs/content-engine/rich-text) JSON
instead of HTML; the migration keeps the words of existing articles as one
paragraph, so re-check their formatting. Run your migrations after you upgrade
`@vitnode/blog`:

```bash tab="bun"
bun run db:migrate
```

```bash tab="pnpm"
pnpm db:migrate
```

```bash tab="npm"
npm run db:migrate
```

</Tabs>

## Deliver it from a plugin [#deliver-it-from-a-plugin]

Build the public article page in a plugin too, then use the Content Engine
delivery guide for loaders and SEO. That keeps the data model and its public URL
together.

<Cards>
  <Card
    icon={<RouteIcon />}
    title="Build your first plugin"
    description="Create the plugin that will own your site’s public blog route."
    href="/docs/guides/first-plugin"
  />
  <Card
    icon={<CompassIcon />}
    title="Content delivery and SEO"
    description="Add plugin routes, redirects, canonical metadata, and sitemaps."
    href="/docs/content-engine/public-pages"
  />
  <Card
    icon={<LayoutDashboardIcon />}
    title="Admin Control Panel"
    description="Extend the staff experience with pages, navigation, and widgets."
    href="/docs/dev/plugins/admin"
  />
</Cards>

# Build Your First Plugin (/docs/guides/first-plugin)

This tutorial builds `@acme/site-notes`, a tiny plugin with a page at
`/site-notes`. Start from a VitNode workspace with Turborepo enabled; it gives
the plugin generator a shared home.

### Generate `@acme/site-notes` [#generate-acmesite-notes]

Run the generator from the workspace root and enter `@acme/site-notes` when it
asks for a name:

```bash tab="bun"
bun create vitnode-app@canary --plugin
```

```bash tab="pnpm"
pnpm create vitnode-app@canary --plugin
```

```bash tab="npm"
npm create vitnode-app@canary -- --plugin
```

</Tabs>

The result has `routes.ts`, `pages/home-page.tsx`, `locales/en.json`, and
`config.tsx`. The CLI adds a workspace dependency but leaves activation to you,
which makes installed plugins predictable.

</Step>
  <Step>

### Claim the page URL [#claim-the-page-url]

The route tree belongs to the plugin and is all the host needs to discover a
route. `lazy` names the page module without importing it, so the page gets a
chunk of its own:

```ts title="plugins/site-notes/src/routes.ts"
import { definePluginRoutes, lazy, page } from '@vitnode/core/routing'

export const routes = definePluginRoutes([
  // [!code ++:3]
  page('/site-notes', {
    component: lazy(() => import('./pages/home-page')),
  }),
])
```

</Step>
  <Step>

### Render a translated page [#render-a-translated-page]

Edit the generated route module. It stays framework-neutral and is lazily
loaded by the TanStack Start host:

```tsx title="plugins/site-notes/src/pages/home-page.tsx"
import { useTranslations } from 'use-intl'

const HomePage = () => {
  const t = useTranslations('@acme/site-notes') // [!code ++]

return (
    <div className="container mx-auto flex max-w-2xl flex-col gap-4 p-4">
      <h2 className="text-2xl font-semibold">{t('home.title')}</h2>
      <p className="text-muted-foreground">{t('home.desc')}</p>
    </div>
  )
}

export default HomePage
```

```json title="plugins/site-notes/src/locales/en.json"
{
  "@acme/site-notes": {
    "home": {
      "title": "Site notes",
      "desc": "This page ships from a plugin. Neat, right?"
    }
  }
}
```

</Step>
  <Step>

### Enable it in the host [#enable-it-in-the-host]

The package must be in the host's `plugins` array. This is the only composition
step; routes and pages remain inside `plugins/site-notes`:

```ts title="apps/web/src/vitnode.config.ts"
import { siteNotesPlugin } from '@acme/site-notes/config' // [!code ++]

export const vitNodeConfig = buildConfig({
  plugins: [
    siteNotesPlugin(), // [!code ++]
  ],
})
```

</Step>
  <Step>

### Run and inspect the result [#run-and-inspect-the-result]

```bash tab="bun"
bun dev
```

```bash tab="pnpm"
pnpm dev
```

```bash tab="npm"
npm run dev
```

</Tabs>

Visit `http://localhost:3000/site-notes`.

{/* Image prompt: Tutorial verification screenshot for a VitNode app at /site-notes. Show a simple “Site notes” page, browser address bar, and a compact visual hint that it is loaded from a plugin package. Dark theme, 1440x900. */}

</Step>
</Steps>

## Grow the same plugin [#grow-the-same-plugin]

<Cards>
  <Card
    icon={<RouteIcon />}
    title="Add route behavior"
    description="Use loaders, metadata, breadcrumbs, and parameters in the plugin route."
    href="/docs/dev/routing"
  />
  <Card
    icon={<NetworkIcon />}
    title="Add an API module"
    description="Keep typed Hono routes beside the page that needs them."
    href="/docs/dev/plugins/api/modules"
  />
  <Card
    icon={<LayoutDashboardIcon />}
    title="Add AdminCP tools"
    description="Give staff a plugin-owned screen or dashboard widget."
    href="/docs/dev/plugins/admin"
  />
</Cards>

# Guides (/docs/guides)

Guides are the shortest trustworthy path from an empty workspace to a feature
you can click. They start in a plugin on purpose: reusable code deserves a
proper home before it acquires a spare drawer in the host app.

<Cards>
  <Card
    icon={<PackagePlusIcon />}
    href="/docs/guides/first-plugin"
    title="Build your first plugin"
    description="Generate a plugin, add a page, register it, and visit its route."
  />
  <Card
    icon={<NotebookPenIcon />}
    href="/docs/guides/blog"
    title="Install the Blog plugin"
    description="Enable @vitnode/blog, publish an article in AdminCP, and deliver it from a plugin."
  />
</Cards>

Already have an app? Great. If not, [Getting started](/docs/dev/setup) prepares
the database and your first AdminCP account. Need a precise option instead of a
walkthrough? The [development reference](/docs/dev) is close by, wearing its
tiny lab coat.

# Accessibility (/docs/ui/accessibility)

Every interactive component sits on a [Base UI](https://base-ui.com) primitive,
so keyboard support, focus management and ARIA come built in. Your job is mostly
not to break it. Try the demos with a keyboard or a screen reader.

## Keyboard focus [#keyboard-focus]

Rings use `:focus-visible`, so they show up for keyboards and stay out of the
way for mice. Text fields always get one, since you're about to type. Custom
controls should borrow the same classes.

```tsx
<div
  tabIndex={0}
  className="outline-none focus-visible:ring-3 focus-visible:ring-ring/50"
/>
```

## Touch targets [#touch-targets]

Small controls keep their compact look but get an invisible `::after` hit area
of at least 44px. `Checkbox`, `RadioGroupItem` and `Switch` always have it; the
smaller icon `Button` sizes and `NumberField` steppers add it on touch screens via
`pointer-coarse:`.

## Contrast [#contrast]

The ratio is computed from the live theme tokens, so flip dark mode and watch it
change. `muted-foreground` passes AA on `background` and `card` in both themes.
Filled `primary` with white text drops to about 3.8:1 in dark mode, so keep it
for short button labels.

## Screen reader text [#screen-reader-text]

Icons are decoration; words carry the meaning. Icon-only `Button` sizes require
an `aria-label` at the type level, and `sr-only` adds context that sighted users
get from the layout.

```tsx
<Badge>
  {unread}
  <span className="sr-only"> unread</span>
</Badge>
```

## Announcements [#announcements]

Changes that happen without a page load need to be said out loud. `role="status"`
waits politely for a pause; `role="alert"` interrupts. `Alert` picks for you:
`warning` and `destructive` are alerts, everything else is a status.
`FieldError` is an alert, `Spinner` is a labelled status, and a loading `Button`
renames itself to "Loading".

## Motion and transparency [#motion-and-transparency]

These are your device's settings right now. Components respect them with
`motion-reduce:`, `reduced-transparency:` and `pointer-coarse:`, so nobody
gets a spinning headache or a blurry dialog they asked not to have. More in
[Motion](/docs/ui/motion).

## Semantic HTML [#semantic-html]

```tsx
<header>…</header>
<nav aria-label="Main">…</nav>
<main>
  <h1>Settings</h1>
  <img alt="Your avatar" src={avatarUrl} />
  <img alt="" src="/divider.svg" />
</main>
```

- Use `header`, `nav`, `main` and real headings in order. Screen reader users
  jump between them like chapters.
- Every image needs `alt`. Use `alt=""` only when it is purely decorative.
- A `button` does things, a link goes places. Never put `onClick` on a `div`.

## Related [#related]

# Accordion (/docs/ui/accordion)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from '@vitnode/core/components/ui/accordion'
```

```tsx
<Accordion defaultValue={['register']}>
  <AccordionItem value="register">
    <AccordionTrigger>How do I create an account?</AccordionTrigger>
    <AccordionContent>
      <p>Click Sign up in the top bar and fill in your email.</p>
    </AccordionContent>
  </AccordionItem>
</Accordion>
```

`defaultValue` and `value` are arrays of item values, even when only one item
can be open.

## Multiple [#multiple]

By default, opening an item closes the others. `multiple` lets several stay
open.

```tsx
<Accordion defaultValue={['kind', 'search']} multiple>
```

## Find in page [#find-in-page]

With `hiddenUntilFound`, closed panels stay in the DOM and the browser's

<kbd>Ctrl</kbd> + <kbd>F</kbd> can find and open them. Great for long FAQs.

```tsx
<Accordion hiddenUntilFound>
```

## API Reference [#api-reference]

[Base UI - Accordion](https://base-ui.com/react/components/accordion)

# Alert Dialog (/docs/ui/alert-dialog)

Unlike a [Dialog](/docs/ui/dialog), clicking outside does nothing. People
answer with a button, or back out with <kbd>Escape</kbd>.

## Preview [#preview]

## Usage [#usage]

```ts
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogTrigger,
} from '@vitnode/core/components/ui/alert-dialog'
import { Button } from '@vitnode/core/components/ui/button'
```

```tsx
<AlertDialog>
  <AlertDialogTrigger
    render={<Button variant="destructive">Delete thread</Button>}
  />
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this thread?</AlertDialogTitle>
      <AlertDialogDescription>
        All 42 replies go with it. This can't be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction variant="destructive">Delete thread</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

Both `AlertDialogAction` and `AlertDialogCancel` close the dialog. Put your
logic in the action's `onClick`.

## Icon and compact size [#icon-and-compact-size]

`AlertDialogMedia` adds an icon tile. With `size="sm"` the dialog gets narrower,
centers its text and splits the footer into two equal buttons.

```tsx
<AlertDialogContent size="sm">
  <AlertDialogHeader>
    <AlertDialogMedia>
      <LogOutIcon />
    </AlertDialogMedia>
    <AlertDialogTitle>Sign out of all devices?</AlertDialogTitle>
  </AlertDialogHeader>
</AlertDialogContent>
```

Waiting on an API call before closing? [Confirm Action Alert
Dialog](/docs/ui/confirm-action-alert-dialog) handles the spinner and errors
for you.

## Props [#props]

`AlertDialogAction` and `AlertDialogCancel` also take `size`. Read the open
state from children with `useAlertDialog()`.

## API Reference [#api-reference]

[Base UI - Alert Dialog](https://base-ui.com/react/components/alert-dialog#api-reference)

# Alert (/docs/ui/alert)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Alert,
  AlertDescription,
  AlertTitle,
} from '@vitnode/core/components/ui/alert'
```

```tsx
<Alert variant="warning">
  <AlertTitle>Cron adapter missing</AlertTitle>
  <AlertDescription>
    Scheduled jobs won't run until you configure one.
  </AlertDescription>
</Alert>
```

Alerts match the callouts in these docs and the
[Editor](/docs/ui/editor#panels) panels, so a warning reads the same
everywhere.

## Variants [#variants]

- `default` - a neutral note on a plain card, with no icon.
- `info` - useful context.
- `success` - something finished and went well.
- `warning` - a non-blocking caution worth acting on.
- `destructive` - an error or a failed action.

Every variant except `default` brings its own icon.

## Screen readers [#screen-readers]

`warning` and `destructive` get `role="alert"`, so screen readers interrupt to
read them. The rest use `role="status"` and wait their turn. For a static hint
that's on the page from the start, pass `role="note"`:

```tsx
<Alert role="note" variant="warning">
  <AlertTitle>Exports run nightly</AlertTitle>
</Alert>
```

## Custom icon [#custom-icon]

Pass any icon to `icon`, or `null` for none.

```tsx
<Alert icon={<HardDriveIcon />} variant="info">
  <AlertTitle>Storage is connected</AlertTitle>
</Alert>
```

## Dismissible [#dismissible]

`AlertAction` pins a control to the top end corner, and the alert makes room
for it.

```tsx
<Alert variant="warning">
  <AlertTitle>Maintenance tonight at 22:00</AlertTitle>
  <AlertAction>
    <Button aria-label="Dismiss" size="icon-sm" variant="ghost">
      <XIcon />
    </Button>
  </AlertAction>
</Alert>
```

## Props [#props]

# Aspect Ratio (/docs/ui/aspect-ratio)

## Preview [#preview]

## Usage [#usage]

```ts
import { AspectRatio } from '@vitnode/core/components/ui/aspect-ratio'
```

```tsx
<AspectRatio className="overflow-hidden rounded-lg" ratio={16 / 9}>
  <img
    alt="Forum dashboard"
    className="size-full object-cover"
    src="/dashboard.webp"
  />
</AspectRatio>
```

The box fills its width and derives its height from `ratio`, so nothing jumps
while the image loads. `size-full object-cover` fills it without stretching.

## Common ratios [#common-ratios]

`ratio` is width divided by height: `16 / 9` for video, `4 / 3` for photos, `1`
for avatars, `9 / 16` for phone screenshots.

## Video embed [#video-embed]

```tsx
<AspectRatio ratio={16 / 9}>
  <iframe
    allowFullScreen
    className="size-full rounded-lg"
    src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
    title="Getting started with VitNode"
  />
</AspectRatio>
```

Give every `iframe` a `title`, so screen readers can name it.

## Props [#props]

Every other prop goes to the underlying `div`.

# Attachment (/docs/ui/attachment)

## Preview [#preview]

Pick a file and watch the progress bar. Hit × mid-upload to cancel.

## Usage [#usage]

`AutoFormFile` takes one file, `AutoFormFiles` takes many. The form stores
**file ids**: a number for one file, an array of numbers for many.

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormFile } from '@vitnode/core/components/form/fields/file'
import { AutoFormFiles } from '@vitnode/core/components/form/fields/files'

const formSchema = z.object({
  avatar: z.number().nullable().default(null),
  gallery: z.array(z.number()).max(4).default([]),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'avatar',
      component: (props) => (
        <AutoFormFile
          {...props}
          allowedExtensions={['.png', '.jpg', '.webp']}
          label="Avatar"
          maxBytes={5 * 1024 * 1024}
          onUpload={uploadFile}
        />
      ),
    },
    {
      id: 'gallery',
      component: (props) => (
        <AutoFormFiles
          {...props}
          label="Gallery"
          maxBytes={5 * 1024 * 1024}
          maxItems={4}
          onUpload={uploadFile}
        />
      ),
    },
  ]}
/>
```

</Tab>

```ts
import {
  Attachment,
  AttachmentAction,
  AttachmentActions,
  AttachmentContent,
  AttachmentDescription,
  AttachmentMedia,
  AttachmentTitle,
} from '@vitnode/core/components/ui/attachment'
```

```tsx
<Attachment>
  <AttachmentMedia variant="image">
    <img alt="" src={file.url} />
  </AttachmentMedia>
  <AttachmentContent>
    <AttachmentTitle>{file.name}</AttachmentTitle>
    <AttachmentDescription>48 KB</AttachmentDescription>
  </AttachmentContent>
  <AttachmentActions>
    <AttachmentAction aria-label={`Remove ${file.name}`} onClick={remove}>
      <XIcon />
    </AttachmentAction>
  </AttachmentActions>
</Attachment>
```

</Tab>
</Tabs>

## Uploading [#uploading]

`onUpload(file, { onProgress, signal })` uploads the picked `File` and returns
the stored file (`{ id, name, size, url, mimeType? }`). The field saves its `id`.

- Call `onProgress(fraction)` with `0` to `1` to show a percentage. Skip it and
  the card shimmers instead.
- Pass `signal` to your request. Cancelling from the card aborts it, and any late
  response is ignored.
- Throw to fail. The file stays as an error card with a **Try again** button.

`fetch` can't report upload progress, so use `XMLHttpRequest` for the bar:

```ts
import type {
  AutoFormFileValue,
  FileUploadOptions,
} from '@vitnode/core/components/form/fields/file'

const uploadFile = async (
  file: File,
  { onProgress, signal }: FileUploadOptions,
): Promise<AutoFormFileValue> =>
  await new Promise((resolve, reject) => {
    const body = new FormData()
    body.append('file', file)

const xhr = new XMLHttpRequest()
    xhr.open('POST', '/api/my-plugin/uploads')
    xhr.responseType = 'json'
    xhr.upload.onprogress = (event) => {
      if (event.lengthComputable) onProgress(event.loaded / event.total)
    }
    xhr.onload = () =>
      xhr.status < 300
        ? resolve(xhr.response)
        : reject(new Error('Upload failed'))
    xhr.onerror = () => reject(new Error('Upload failed'))
    signal.addEventListener('abort', () => xhr.abort())
    xhr.send(body)
  })
```

## Removing and existing files [#removing-and-existing-files]

Removing a file from `AutoFormFiles` shows a toast with **Undo**, which puts it
back in the same spot. Misclicks shouldn't cost a re-upload.

Editing a record with files? Pass `file={existing}` or `files={existing}` to
show them.

## Limits [#limits]

Files are checked **before** upload, so nobody waits on a 2 GB video just to
hear it's too big.

| Prop                | Field           | Example                        |
| ------------------- | --------------- | ------------------------------ |
| `maxBytes`          | both, required  | `5 * 1024 * 1024`              |
| `allowedExtensions` | both            | `['.pdf', '.png']` (lowercase) |
| `allowedMimeTypes`  | both            | `['image/png']`                |
| `maxItems`          | files, required | `4`                            |
| `minItems`          | files           | `1`                            |
| `ordered`           | files           | `false` turns off reordering   |

Files reorder by drag or keyboard. Check the same limits on your server: the
browser check can't stop someone determined.

## States [#states]

Set `state` on `Attachment`: `idle`, `uploading`, `processing`, `done`
(default) or `error`. In `error`, say what went wrong.

## Layouts [#layouts]

- `size`: `default`, `sm` or `xs` for chat composers and tight lists.
- `orientation="vertical"` turns it into a card with a big preview.
- `AttachmentGroup` makes a horizontal scroll row that fades at the edges.
- `AttachmentTrigger` makes the whole attachment clickable. Render it as a link
  to open the file. Focus shows one ring on the attachment, not two.
- `AttachmentTitle` keeps the extension visible and truncates the rest:
  `quarterly-rep….pdf`.

## Accessibility [#accessibility]

- Give every `AttachmentAction` an `aria-label` naming the file: "Remove
  report.pdf". Plain "Remove" is a riddle when there are five files.
- Previews sit next to the file name, so `alt=""` is right.
- The fields announce reordering and list each rejected file with the reason.
- The whole drop zone is clickable. It only lights up when the drag carries
  files.
- On touch screens, actions and drag handles grow to a 40px hit area.

# Auto Form (/docs/ui/auto-form)

## Preview [#preview]

## Usage [#usage]

```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormInput } from '@vitnode/core/components/form/fields/input'
import { z } from 'zod'

const formSchema = z.object({
  username: z
    .string()
    .min(3, 'Usernames need at least 3 characters')
    .default(''),
  email: z.email().describe('Only used for notifications.').default(''),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'username',
      component: (props) => <AutoFormInput {...props} label="Username" />,
    },
    {
      id: 'email',
      component: (props) => (
        <AutoFormInput {...props} label="Email" type="email" />
      ),
    },
  ]}
  onSubmit={(values) => {
    toast.success('Account created', { description: values.username })
  }}
/>
```

The schema drives validation, defaults and HTML attributes. Each field's `id`
points at a schema key, and `component` decides how it looks.

## Field types [#field-types]

Import each one from `@vitnode/core/components/form/fields/<file>`. Spread
`props` first, then your own props. Spread it last and the schema's empty
`description` overwrites yours.

| Component                | File              | Docs                                              |
| ------------------------ | ----------------- | ------------------------------------------------- |
| `AutoFormInput`          | `input`           | [Input](/docs/ui/input)                           |
| `AutoFormTextarea`       | `textarea`        | [Textarea](/docs/ui/textarea)                     |
| `AutoFormCheckbox`       | `checkbox`        | [Checkbox](/docs/ui/checkbox)                     |
| `AutoFormSwitch`         | `switch`          | [Switch](/docs/ui/switch)                         |
| `AutoFormRadioGroup`     | `radio-group`     | [Radio Group](/docs/ui/radio-group)               |
| `AutoFormSelect`         | `select`          | [Select](/docs/ui/select)                         |
| `AutoFormCombobox`       | `combobox`        | [Combobox](/docs/ui/combobox)                     |
| `AutoFormCascader`       | `cascader`        | [Cascader](/docs/ui/cascader)                     |
| `AutoFormNumber`         | `number`          | [Number Field](/docs/ui/number-field)             |
| `AutoFormNullableNumber` | `nullable-number` | [Nullable Number](/docs/ui/nullable-number)       |
| `AutoFormInputOTP`       | `input-otp`       | [Input OTP](/docs/ui/input-otp)                   |
| `AutoFormColor`          | `color`           | [Color](/docs/ui/color)                           |
| `AutoFormEmojiIcon`      | `emoji-icon`      | [Emoji & Icon Picker](/docs/ui/emoji-icon-picker) |
| `AutoFormEditor`         | `editor`          | [Editor](/docs/ui/editor)                         |
| `AutoFormFile`           | `file`            | [Attachment](/docs/ui/attachment)                 |
| `AutoFormFiles`          | `files`           | [Attachment](/docs/ui/attachment)                 |
| `AutoFormRoles`          | `input-roles`     | [Roles](/docs/ui/roles)                           |
| `AutoFormUser`           | `input-users`     | [User](/docs/ui/user)                             |
| `AutoFormDatePicker`     | `date-picker`     | [Date Picker](/docs/ui/date-picker)               |
| `AutoFormDateTime`       | `date-time`       | -                                                 |
| `AutoFormArray`          | `array`           | [Arrays](#arrays)                                 |

Every field takes `label`, `labelRight` (content pinned to the label's right
edge) and `description`.

## Schema [#schema]

```ts
const formSchema = z.object({
  username: z.string().min(3).max(20).default('captain'),
  bio: z.string().describe('Shown on your profile card.').optional(),
  role: z.enum(['member', 'admin']).default('member'),
})
```

- Fields are required unless the schema says `.optional()`. Optional fields get
  an "Optional" hint next to the label.
- `.default()` sets the starting value. Give required strings `.default('')`:
  without it an untouched field says "expected string, received undefined"
  instead of your `.min()` message.
- `.describe()` becomes the description, unless you pass `description`.
- String `.min()`, `.max()` and `.regex()` become `minLength`, `maxLength` and
  `pattern` on the control. `z.enum()` values feed selects and radio groups.
- Any Zod check works, `.refine()` included. Its `message` is what users see.

## Validation [#validation]

By default a message appears once you leave a field, then updates live as you
type. Switch the modes above to feel the difference.

| `mode`                  | A field's message appears…     |
| ----------------------- | ------------------------------ |
| `"onTouched"` (default) | once the field has been left   |
| `"onBlur"`              | once the field has been left   |
| `"onChange"` / `"all"`  | as soon as the field is edited |
| `"onSubmit"`            | after the first submit attempt |

The submit button stays enabled while the form is invalid. Pressing it never
calls `onSubmit`. Instead every message appears, invalid fields shake, and
focus jumps to the first one.

```tsx
<AutoForm formSchema={formSchema} fields={fields} mode="onChange" />
```

## Submit [#submit]

`onSubmit` receives the parsed values, the TanStack Form instance, and
`{ captchaToken, intent }`. While it runs, the button shows a spinner.

```tsx
import type { AutoFormOnSubmit } from '@vitnode/core/components/form/auto-form'

const onSubmit: AutoFormOnSubmit<typeof formSchema> = async (values, form) => {
  await saveProfile(values)
  form.reset()
  toast.success('Profile saved', { description: values.username })
}
```

Restyle the button with `submitButtonProps`:

```tsx
<AutoForm
  submitButtonProps={{ children: 'Save changes', variant: 'outline' }}
/>
```

Pass a route's `captcha` config and the button waits for the captcha to load.
Send `captchaToken` along with your request.

<Callout>
  Inside a [Dialog](/docs/ui/dialog), AutoForm renders a footer with Cancel and
  Submit. Any form with unsaved changes asks before the page unloads.
</Callout>

### Errors from the server [#errors-from-the-server]

The API said no? Put its message on the field with `setFormFieldError`. It
focuses the field, blocks submit while the rejected value stays, and clears
once the user edits it.

```tsx
import { setFormFieldError } from "@vitnode/core/components/form/auto-form";

onSubmit={async (values, form) => {
  const res = await updateUsername(values);
  if (res.status === 409) {
    setFormFieldError(form, "username", "That username is taken");
  }
}}
```

## Tabs [#tabs]

Pass `tabs` and tag fields with `tab`. Untagged fields go to the first tab. All
panels stay mounted, so values survive tab switches.

Press Save on **General** above. The error lives on **SEO**, so AutoForm
switches there, and tabs hiding an error get a red dot.

```tsx
<AutoForm
  tabs={[
    { value: 'general', label: 'General' },
    { value: 'seo', label: 'SEO' },
  ]}
  fields={[
    {
      id: 'name',
      component: (props) => <AutoFormInput {...props} label="Name" />,
    },
    {
      id: 'metaTitle',
      tab: 'seo',
      component: (props) => <AutoFormInput {...props} label="Meta title" />,
    },
  ]}
/>
```

## Conditional fields [#conditional-fields]

`hidden` gets the live values. Return `true` to hide the field.

```tsx
{
  id: "password",
  hidden: values => values.visibility !== "password",
  component: props => <AutoFormInput {...props} label="Forum password" type="password" />,
}
```

<Callout type="warn">
  Hidden fields still submit. Make them `.optional()` or give them a
  `.default()`, or an invisible error blocks the form.
</Callout>

### Nested fields [#nested-fields]

A switch and the settings it unlocks can share one card. Pass them as
`children` of an `AutoFormSwitch` field: they expand when it's on.

```tsx
{
  id: "allow_uploads",
  component: props => <AutoFormSwitch {...props} label="Allow uploads" />,
  children: [
    {
      id: "max_storage",
      component: props => <AutoFormNumber {...props} label="Maximum file size" />,
    },
  ],
}
```

Children unmount while the switch is off, so give them a `.default()`. They can
have their own `hidden`. Their `tab` is ignored: they live in the parent's tab.

## Arrays [#arrays]

`AutoFormArray` edits a `z.array(z.object(...))` as rows you can add and
remove. Schema `.min()` and `.max()` limit the rows.

```tsx
{
  id: "links",
  component: props => (
    <AutoFormArray
      {...props}
      label="Sidebar links"
      addButtonLabel="Add link"
      fields={[
        { id: "title", component: p => <AutoFormInput {...p} label="Title" /> },
        { id: "url", component: p => <AutoFormInput {...p} label="URL" /> },
      ]}
    />
  ),
}
```

| Prop               | Type                              | Default                |
| ------------------ | --------------------------------- | ---------------------- |
| `fields`           | `{ id, component, className? }[]` | required               |
| `addButtonLabel`   | `string`                          | `"Add Item"`           |
| `minItems`         | `number`                          | schema `.min()` or `0` |
| `maxItems`         | `number`                          | schema `.max()`        |
| `showRemoveButton` | `boolean`                         | `true`                 |
| `className`        | `string`                          | -                      |

## Layout [#layout]

For a simple grid, `className` is enough:

```tsx
<AutoForm className="grid grid-cols-1 gap-4 md:grid-cols-2" />
```

For full control, `layout` receives every rendered field by `id`. You place
the submit button yourself with `AutoFormSubmitButton`. Give it an `intent` to
tell buttons apart in `onSubmit`.

```tsx
import {
  AutoForm,
  AutoFormSubmitButton,
} from '@vitnode/core/components/form/auto-form'
```

```tsx
<AutoForm
  layout={(rendered) => (
    <>
      <div className="grid grid-cols-1 gap-6 sm:grid-cols-2">
        {rendered.firstName}
        {rendered.lastName}
      </div>
      <AutoFormSubmitButton intent="draft" variant="ghost">
        Save draft
      </AutoFormSubmitButton>
      <AutoFormSubmitButton intent="publish">Publish</AutoFormSubmitButton>
    </>
  )}
  onSubmit={(values, form, { intent }) => {}}
/>
```

## Custom fields [#custom-fields]

A field is any component. Build it from AutoForm's parts and it gets the same
ids, ARIA and errors as the built-in ones:

- `AutoFormLabel` and `AutoFormDesc` render the label and description.
- `FormControl` passes `id`, `aria-invalid` and `aria-describedby` to its child.
- `FormMessage` shows the field's errors.

Type `field` with `FormFieldApi<TValue>` so a wrong value is a build error.
`field.onChange` takes the value or a DOM change event.

```tsx
import type {
  FormFieldApi,
  ItemAutoFormComponentProps,
} from '@vitnode/core/components/form/auto-form'
import { AutoFormDesc } from '@vitnode/core/components/form/common/desc'
import { AutoFormLabel } from '@vitnode/core/components/form/common/label'
import { FormControl, FormMessage } from '@vitnode/core/components/ui/form'

const SlowModeField = ({
  label,
  description,
  field,
}: Omit<ItemAutoFormComponentProps, 'field'> & {
  field: FormFieldApi<number>
}) => (
  <>
    <AutoFormLabel>{label}</AutoFormLabel>
    <FormControl>
      <input
        type="range"
        max={120}
        name={field.name}
        value={field.value}
        onBlur={field.onBlur}
        onChange={(e) => field.onChange(Number(e.target.value))}
      />
    </FormControl>
    {!!description && <AutoFormDesc>{description}</AutoFormDesc>}
    <FormMessage />
  </>
)
```

For a two-column settings row, wrap the parts in [Field](/docs/ui/field#inside-a-custom-autoform-field).

## Multi-language fields [#multi-language-fields]

`AutoFormInput`, `AutoFormTextarea` and `AutoFormEditor` take `multiLang`. The
value becomes `{ languageCode, value }[]`, and a language select appears when
more than one language is enabled. It only switches what you're editing, not
the app locale.

```ts
import { multiLangValueSchema } from '@vitnode/core/lib/helpers/multi-lang'

const formSchema = z.object({
  name: multiLangValueSchema({ minLength: 1, maxLength: 255 }).min(1),
})
```

```tsx
{ id: "name", component: props => <AutoFormInput {...props} label="Name" multiLang /> }
```

- `minLength` and `maxLength` apply to each language's value.
- Languages come from [`i18n.locales`](/docs/dev/i18n), minus any with
  [`enabled: false`](/docs/dev/i18n#disabling-one).
- The select opens on the first language with text: yours, then the form's
  default (a content type's `defaultLocale`), then any other. Empty editor
  markup like `<p></p>` counts as empty.

### Saving to the backend [#saving-to-the-backend]

`saveLanguageWords` stores the array in `core_languages_words`, replacing the
old rows in one transaction.

```ts title="plugins/{plugin_name}/src/api/routes/create-category.route.ts"
import { saveLanguageWords } from '@vitnode/core/api/lib/save-language-words'

await saveLanguageWords(c, {
  pluginCode: 'blog',
  tableName: 'blog_categories',
  variable: 'name',
  itemId: category.id,
  values: name,
})
```

To prefill an edit form, query `core_languages_words` by the same
`(pluginCode, tableName, variable, itemId)` and return
`{ languageCode, value }[]`, like
[`resolveRoleNames`](/docs/dev/working-with-users/roles) does.

## Props [#props]

<TypeTable
  type={{
    formSchema: {
      description:
        'Zod object that drives validation, defaults and attributes.',
      type: 'z.ZodObject',
      required: true,
    },
    fields: {
      description: 'Field definitions, rendered in order.',
      type: '{ id, component, tab?, hidden?, children? }[]',
      required: true,
    },
    onSubmit: {
      description: 'Runs with valid values only.',
      type: '(values, form, { captchaToken, intent }) => void | Promise<void>',
    },
    mode: {
      description: 'When field messages appear.',
      type: '"onTouched" | "onBlur" | "onChange" | "all" | "onSubmit"',
      default: '"onTouched"',
    },
    tabs: {
      description: 'Splits fields into tabs. Fields pick one with `tab`.',
      type: '{ value: string; label: ReactNode }[]',
    },
    layout: {
      description:
        'Places rendered fields yourself. No submit button is added, use `AutoFormSubmitButton`.',
      type: '(rendered: Record<string, ReactNode>) => ReactNode',
    },
    submitButtonProps: {
      description: 'Props for the default submit button.',
      type: 'ButtonProps',
    },
    captcha: {
      description: "The route's captcha config. Adds the widget and a token.",
      type: 'RouteCaptcha',
    },
    canSubmitWhenInvalid: {
      description: "Passed to TanStack Form's option of the same name.",
      type: 'boolean',
      default: 'true',
    },
    children: {
      description: 'Rendered after the fields, before the submit button.',
      type: 'ReactNode',
    },
  }}
/>

Any other `<form>` prop (`className`, `id`, `onKeyDown`) goes to the form
element.

# Avatar (/docs/ui/avatar)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Avatar,
  AvatarFallback,
  AvatarImage,
} from '@vitnode/core/components/ui/avatar'
```

```tsx
<Avatar>
  <AvatarImage alt="Ada Lovelace" src={user.avatarUrl} />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>
```

## Fallback [#fallback]

The fallback shows while the image loads and stays if it never arrives. Once
loaded, the image fades in instead of popping.

## Sizes [#sizes]

```tsx
<Avatar size="sm" />
<Avatar />
<Avatar size="lg" />
```

## Badge [#badge]

`AvatarBadge` adds a status dot. Give it a semantic background:

```tsx
<Avatar>
  <AvatarImage alt="Ada Lovelace" src={user.avatarUrl} />
  <AvatarFallback>AL</AvatarFallback>
  <AvatarBadge className="bg-success" />
</Avatar>
```

A dot alone doesn't tell everyone someone is online. Say it in text too, or
give the badge an `aria-label`.

## Group [#group]

`AvatarGroup` stacks avatars. Wrap each in `AvatarGroupItem` to lift it on
hover and show a tooltip, and end with `AvatarGroupCount`:

```ts
import {
  AvatarGroup,
  AvatarGroupCount,
  AvatarGroupItem,
} from '@vitnode/core/components/ui/avatar'
```

```tsx
<AvatarGroup>
  {users.map((user) => (
    <AvatarGroupItem key={user.id} label={user.name}>
      <Avatar>
        <AvatarImage alt={user.name} src={user.avatarUrl} />
        <AvatarFallback>{user.initials}</AvatarFallback>
      </Avatar>
    </AvatarGroupItem>
  ))}
  <AvatarGroupCount>+3</AvatarGroupCount>
</AvatarGroup>
```

The whole group shares one tooltip, so it glides from face to face. Plain
`Avatar`s inside a group make a quiet stack with no hover effect.

## Member avatars [#member-avatars]

For VitNode users, reach for `Avatar` from `@vitnode/core/components/avatar`.
It shows the stored picture, or the first letter of `nameCode` on the
member's `avatarColor` in white.

```ts
import { Avatar } from '@vitnode/core/components/avatar'
```

```tsx
<Avatar size={32} user={user} />
```

`user` needs `name`, `nameCode`, `avatarColor` (hex without `#`) and an
optional `avatarUrl`. A broken `avatarUrl` falls back to the letter.

## Accessibility [#accessibility]

- Always pass `alt` to `AvatarImage`. The person's name is usually perfect.
- An `AvatarGroupItem` with a `label` is focusable, and its tooltip opens on
  focus as well as hover.
- With reduced motion, group avatars stay put and only the tooltip appears.

## Props [#props]

### Avatar [#avatar]

### AvatarGroupItem [#avatargroupitem]

## API Reference [#api-reference]

[Base UI - Avatar](https://base-ui.com/react/components/avatar)

# Badge (/docs/ui/badge)

## Usage [#usage]

```ts
import { Badge } from '@vitnode/core/components/ui/badge'
```

```tsx
<Badge variant="success">Published</Badge>
```

## Variants [#variants]

Let the word carry the meaning and the color back it up.

| Variant                           | Use it for                                  |
| --------------------------------- | ------------------------------------------- |
| `default`                         | A prominent, neutral label.                 |
| `secondary` / `outline` / `ghost` | Quiet labels in dense UI like tables.       |
| `link`                            | A label that looks like a text link.        |
| `success`                         | Healthy or done: Published, Active, Paid.   |
| `warning`                         | Needs attention: Pending, Expiring, Draft.  |
| `destructive`                     | Failed or blocked: Failed, Banned, Overdue. |

Status variants share their tint with the matching button, so a `success`
badge and a `success` button read as the same idea.

## With an icon [#with-an-icon]

Icons shrink to 12px. Mark them `data-icon="inline-start"` or
`data-icon="inline-end"` to tighten the padding on that side.

```tsx
<Badge variant="success">
  <BadgeCheck data-icon="inline-start" />
  Verified
</Badge>
```

## Counter [#counter]

Numbers are tabular, so counts don't jiggle. Add `min-w-5 px-1` for a round
pill, and `sr-only` text so "8" means something to screen readers.

```tsx
<Badge className="min-w-5 px-1">
  8<span className="sr-only">unread messages</span>
</Badge>
```

## As a link [#as-a-link]

Pass `render` to make the badge a link. Links get a hover state.

```tsx
<Badge render={<a href="/tags/announcements" />} variant="secondary">
  #announcements
</Badge>
```

## Props [#props]

<TypeTable
  type={{
    variant: {
      description: 'The look of the badge.',
      type: 'default | secondary | outline | ghost | link | success | warning | destructive',
      default: 'default',
    },
    render: {
      description: 'Replaces the `span`, such as with an `a`.',
      type: 'ReactElement | ((props, state) => ReactElement)',
    },
  }}
/>

# Bubble (/docs/ui/bubble)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Bubble,
  BubbleContent,
  BubbleGroup,
  BubbleReactions,
} from '@vitnode/core/components/ui/bubble'
```

```tsx
<Bubble>
  <BubbleContent>I removed the stale route. You are welcome.</BubbleContent>
</Bubble>
```

A bubble shrinks to fit its text and never grows past 80% of the row. New
bubbles grow in from their tail corner; with reduced motion they only fade.

## Variants [#variants]

`default` is usually the current user, `secondary` the standard reply. `ghost`
drops the frame and takes the full width.

## Alignment [#alignment]

Your messages go on the end side, everyone else's on the start.

```tsx
<Bubble align="end">
  <BubbleContent>Sent by me.</BubbleContent>
</Bubble>
```

## Grouping [#grouping]

`BubbleGroup` tightens the spacing between consecutive bubbles from one
sender. Set `align` on each `Bubble`, not on the group.

```tsx
<BubbleGroup>
  <Bubble variant="muted">
    <BubbleContent>First thought.</BubbleContent>
  </Bubble>
  <Bubble variant="muted">
    <BubbleContent>Second thought, arriving fashionably late.</BubbleContent>
  </Bubble>
</BubbleGroup>
```

## Reactions [#reactions]

`BubbleReactions` pins a pill to the bubble's edge. It overlaps the bubble, so
leave extra `gap` between rows.

```tsx
<BubbleReactions aria-label="Reactions: rocket, eyes" role="img" side="top">
  <span>🚀</span>
  <span>👀</span>
</BubbleReactions>
```

## Links and buttons [#links-and-buttons]

Use `render` on `BubbleContent` to make a bubble a real link or button, like a
quick-reply suggestion.

```tsx
<Bubble variant="outline">
  <BubbleContent render={<button onClick={onPick} type="button" />}>
    Show me the plugin docs
  </BubbleContent>
</Bubble>
```

## Use with Message [#use-with-message]

For an avatar, sender name or read receipt, wrap bubbles in a
[Message](/docs/ui/message). Bubbles inside follow the message's `align`.

## Accessibility [#accessibility]

- `Bubble` is only the visual surface. Put `role="log"` and an `aria-label` on
  the conversation container.
- Give `BubbleReactions` `role="img"` and an `aria-label`, so screen readers
  announce it once instead of reading every emoji. Interactive reactions should
  be labelled buttons.
- Clickable bubbles must be a real `<button>` or `<a>` via `render`.
- Variants signal tone with color, so keep the meaning in the text too.

## Props [#props]

### Bubble [#bubble]

### BubbleContent [#bubblecontent]

### BubbleReactions [#bubblereactions]

## API Reference [#api-reference]

[Base UI - useRender](https://base-ui.com/react/utils/use-render)

# Button Group (/docs/ui/button-group)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from '@vitnode/core/components/ui/button-group'
```

```tsx
<ButtonGroup aria-label="Message actions">
  <Button variant="outline">Archive</Button>
  <Button variant="outline">Report</Button>
  <Button variant="outline">Snooze</Button>
</ButtonGroup>
```

Inner borders merge and only the outer corners stay round. The buttons need no
extra props.

## Orientation [#orientation]

```tsx
<ButtonGroup aria-label="Zoom" orientation="vertical">
  <Button aria-label="Zoom in" size="icon-sm" variant="outline">
    <ZoomInIcon />
  </Button>
  <Button aria-label="Zoom out" size="icon-sm" variant="outline">
    <ZoomOutIcon />
  </Button>
</ButtonGroup>
```

## Nested groups [#nested-groups]

Groups inside a group get a small gap between them, the classic toolbar look.

```tsx
<ButtonGroup aria-label="Message actions">
  <ButtonGroup>
    <Button aria-label="Go back" size="icon" variant="outline">
      <ArrowLeftIcon />
    </Button>
  </ButtonGroup>
  <ButtonGroup>
    <Button variant="outline">Archive</Button>
    <Button variant="outline">Report</Button>
  </ButtonGroup>
</ButtonGroup>
```

## Separator [#separator]

Borderless variants like `secondary` blur into one blob. Put a
`ButtonGroupSeparator` between them.

```tsx
<ButtonGroup aria-label="Text alignment">
  <Button aria-label="Align left" size="icon" variant="secondary">
    <AlignLeftIcon />
  </Button>
  <ButtonGroupSeparator />
  <Button aria-label="Align center" size="icon" variant="secondary">
    <AlignCenterIcon />
  </Button>
</ButtonGroup>
```

Inside a vertical group, use `<ButtonGroupSeparator orientation="horizontal" />`.

## With text [#with-text]

`ButtonGroupText` is a non-interactive segment, like a counter. Use `render`
to swap the element, for example to a `<label>`.

```tsx
<ButtonGroup aria-label="Quantity">
  <Button aria-label="Decrease quantity" size="icon" variant="outline">
    <MinusIcon />
  </Button>
  <ButtonGroupText aria-live="polite">{quantity}</ButtonGroupText>
  <Button aria-label="Increase quantity" size="icon" variant="outline">
    <PlusIcon />
  </Button>
</ButtonGroup>
```

## With input [#with-input]

An `Input` stretches to fill the free space.

```tsx
<ButtonGroup className="w-full max-w-sm">
  <Input aria-label="Search members" placeholder="Search members..." />
  <Button aria-label="Search" size="icon" variant="outline">
    <SearchIcon />
  </Button>
</ButtonGroup>
```

## Split button [#split-button]

Pair a button with a [Dropdown Menu](/docs/ui/dropdown-menu) trigger.

```tsx
<ButtonGroup>
  <Button variant="outline">Snooze</Button>
  <DropdownMenu>
    <DropdownMenuTrigger
      render={
        <Button
          aria-label="More snooze options"
          size="icon"
          variant="outline"
        />
      }
    >
      <ChevronDownIcon />
    </DropdownMenuTrigger>
    <DropdownMenuContent align="end">
      <DropdownMenuItem>Later today</DropdownMenuItem>
      <DropdownMenuItem>Next week</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</ButtonGroup>
```

## Sizes [#sizes]

The group follows its buttons. Use the same `size` on all of them so heights
match.

## Accessibility [#accessibility]

- The group has `role="group"`. Give it an `aria-label` or `aria-labelledby`.
- Icon-only buttons need their own `aria-label`.
- A focused button lifts above its neighbours, so the focus ring never hides.
- Borders and corners flip correctly in right-to-left languages.
- Need a selected state, like a segmented control? Use
  [Toggle Group](/docs/ui/toggle-group).

## Props [#props]

### ButtonGroup [#buttongroup]

### ButtonGroupText [#buttongrouptext]

<TypeTable
  type={{
    render: {
      description:
        'Replaces the default `<div>`, for example with a `<label>`.',
      type: 'ReactElement | (props, state) => ReactElement',
    },
  }}
/>

### ButtonGroupSeparator [#buttongroupseparator]

All parts accept `className`.

## API Reference [#api-reference]

[shadcn/ui - Button Group](https://ui.shadcn.com/docs/components/base/button-group)

# Button (/docs/ui/button)

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
```

```tsx
<Button>
  <SendIcon />
  Post reply
</Button>
```

A press dips the button to `active:scale-97`, so every click feels
acknowledged. Inside a [Button Group](/docs/ui/button-group) it darkens
instead, and menu triggers stay put.

## Variants [#variants]

Pick the variant by the weight of the action, not your favourite colour:

- `default` - the one primary action on the screen.
- `secondary`, `outline`, `ghost` - supporting actions, loudest to quietest.
- `link` - an action that behaves like navigation.
- `success` - approves or completes something.
- `warning` - risky but reversible, like unpublishing.
- `destructive` - deletes data for good.

Colour never carries the meaning alone. A green button still says "Approve".

## Sizes [#sizes]

Icon-only sizes (`icon`, `icon-xs`, `icon-sm`, `icon-lg`) require an
`aria-label`, and TypeScript will remind you. On touch screens, `icon`,
`icon-sm` and `icon-xs` get an invisible 44px hit area.

## Loading [#loading]

`isLoading` swaps the content for a spinner and disables the button. Loading
always wins: `disabled={false}` won't re-enable it, and screen readers hear
"Loading" instead of your `aria-label`.

```tsx
<Button isLoading={isPending}>Save changes</Button>
```

## Disabled with a reason [#disabled-with-a-reason]

A greyed-out button with no explanation is a riddle. Add `disabledTooltip` to
say _why_.

```tsx
<Button disabled disabledTooltip="You need the Publish permission">
  Publish
</Button>
```

The button then uses `aria-disabled`, so it stays focusable, clicks do nothing,
and screen readers read the reason as its description. The tooltip shows only
while `disabled` is `true` and hides during `isLoading`.

## As a link [#as-a-link]

Use `render` to compose the button with another element. Set
`nativeButton={false}` when that element isn't a `<button>`.

```ts
import { Link } from '@tanstack/react-router'
```

```tsx
<Button nativeButton={false} render={<Link to="/" />}>
  Home
</Button>
```

## Props [#props]

## API Reference [#api-reference]

[Base UI - Button](https://base-ui.com/react/components/button#api-reference)

# Calendar (/docs/ui/calendar)

The Calendar shows a month and lets people pick dates from it. Use it inline for booking or reporting screens. For a form field that opens on click, reach for the [Date Picker](/docs/ui/date-picker) instead.

## Preview [#preview]

## Usage [#usage]

```ts
import { Calendar } from '@vitnode/core/components/ui/calendar'
```

```tsx
const [date, setDate] = React.useState<Date>()

<Calendar mode="single" onSelect={setDate} selected={date} />
```

`Calendar` is built on [React DayPicker](https://daypicker.dev), so every DayPicker prop works.

## Date range [#date-range]

Set `mode="range"` and keep a `DateRange` in state. `numberOfMonths` shows months side by side on wider screens and stacks them on phones.

```ts
import { Calendar, type DateRange } from '@vitnode/core/components/ui/calendar'
```

```tsx
const [range, setRange] = React.useState<DateRange>()

<Calendar mode="range" numberOfMonths={2} onSelect={setRange} selected={range} />
```

## Multiple days [#multiple-days]

`mode="multiple"` collects an array of dates. `max` caps how many can be picked.

```tsx
<Calendar max={3} mode="multiple" onSelect={setDates} selected={dates} />
```

## Disabled days [#disabled-days]

`disabled` takes a date, an array of dates or a matcher. Here: no past days and no weekends.

```tsx
<Calendar
  disabled={[{ before: new Date() }, { dayOfWeek: [0, 6] }]}
  mode="single"
/>
```

## Month and year dropdowns [#month-and-year-dropdowns]

Typing a birthday by clicking "previous month" 300 times is nobody's idea of fun. `captionLayout="dropdown"` adds month and year selects. Set `startMonth` and `endMonth` to bound the years.

```tsx
<Calendar
  captionLayout="dropdown"
  endMonth={new Date()}
  mode="single"
  startMonth={new Date(1926, 0)}
/>
```

Use `dropdown-months` or `dropdown-years` for only one of them.

## Week numbers [#week-numbers]

```tsx
<Calendar mode="single" showWeekNumber />
```

## Today button [#today-button]

Control the visible month with `month` and `onMonthChange`, then jump back from a footer button.

```tsx
const [month, setMonth] = React.useState(new Date())

<Calendar month={month} onMonthChange={setMonth} mode="single" />
<Button onClick={() => setMonth(new Date())}>Today</Button>
```

## Presets [#presets]

Presets are plain buttons that set the range and move the month to it. Handy for analytics filters.

```tsx
<Button
  onClick={() => {
    setRange({ from: addDays(today, -6), to: today })
    setMonth(today)
  }}
>
  Last 7 days
</Button>
```

## Custom day content [#custom-day-content]

Swap the day button through `components.DayButton` and render `CalendarDayButton` with extra children. A `<span>` inside it gets small, muted text automatically. A larger `--cell-size` makes room for it.

```tsx
import {
  Calendar,
  CalendarDayButton,
} from '@vitnode/core/components/ui/calendar'

const PricedDayButton = ({
  children,
  ...props
}: React.ComponentProps<typeof CalendarDayButton>) => (
  <CalendarDayButton {...props}>
    {children}
    <span>${priceFor(props.day.date)}</span>
  </CalendarDayButton>
)

<Calendar
  className="[--cell-size:--spacing(11)]"
  components={{ DayButton: PricedDayButton }}
  mode="single"
/>
```

Define the day button outside your component, so React does not remount every day on each render.

## Appointment picker [#appointment-picker]

Pair the Calendar with a list of time slots. Reset the slot when the day changes.

## Localization [#localization]

The Calendar follows the active VitNode language with no setup. Month names, weekday names, the first day of the week and screen reader labels all come from the browser's `Intl` API, so no extra locale files land in your bundle. In Polish the week starts on Monday, in the US on Sunday.

Need a date-fns locale for something `Intl` can't do? Add `react-day-picker` to your app, then pass the locale as `locale` and the Calendar uses it instead.

```tsx
import { pl } from 'react-day-picker/locale'

<Calendar locale={pl} mode="single" />
```

Force a different first day with `weekStartsOn={1}`.

## Accessibility [#accessibility]

- The grid is a real ARIA grid. Arrow keys move by day and week, Page Up and Page Down by month, Home and End to the edges of a week.
- Each day reads as its full date, plus "Today" and "selected" when they apply.
- Navigation and dropdown labels are translated through `core.global.calendar`.
- Arrows flip in right-to-left languages.

## Props [#props]

`Calendar` accepts every [DayPicker prop](https://daypicker.dev/api/type-aliases/DayPickerProps), plus:

## API Reference [#api-reference]

[React DayPicker](https://daypicker.dev)

# Card (/docs/ui/card)

## Usage [#usage]

```ts
import {
  Card,
  CardAction,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from '@vitnode/core/components/ui/card'
```

```tsx
<Card>
  <CardHeader>
    <CardTitle>Weekly digest</CardTitle>
    <CardDescription>Sent every Monday at 9:00</CardDescription>
  </CardHeader>
  <CardContent>A roundup of the top threads.</CardContent>
  <CardFooter>
    <Button variant="outline">Preview email</Button>
  </CardFooter>
</Card>
```

`CardFooter` has a top border and a soft background, so it always reads as the
"what now?" part. An `img` as the first or last child goes edge to edge with
rounded corners.

## Size [#size]

`size="sm"` drops the spacing from 24px to 16px and shrinks the title. Use it in
dense grids and sidebars.

```tsx
<Card size="sm">...</Card>
```

## Header with border [#header-with-border]

Add `border-b` to `CardHeader` and it gets matching bottom padding.

```tsx
<CardHeader className="border-b">...</CardHeader>
```

## Header and footer [#header-and-footer]

A bordered header plus the footer splits the card into three parts.

## Border separation [#border-separation]

Drop the card padding and let the content draw the lines. `CardAction` keeps a
header button on the end side.

```tsx
<Card className="gap-0 p-0">
  <CardHeader className="items-center px-4 py-2">
    <CardTitle>Reports</CardTitle>
    <CardAction>
      <Button size="sm" variant="outline">
        Filter
      </Button>
    </CardAction>
  </CardHeader>
  <CardContent className="border-y px-4 py-3">...</CardContent>
  <CardFooter className="border-none px-4 py-3">...</CardFooter>
</Card>
```

## With a link [#with-a-link]

A slim footer is a good home for a "read more" link.

```tsx
<CardFooter className="py-2">
  <a className={cn(buttonVariants({ variant: 'link' }), 'px-0')} href="/guide">
    Read the guide
  </a>
</CardFooter>
```

## Props [#props]

All parts take regular `div` props.

### Card [#card]

# Carousel (/docs/ui/carousel)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from '@vitnode/core/components/ui/carousel'
```

```tsx
<Carousel aria-label="Screenshots">
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>
```

[Embla Carousel](https://www.embla-carousel.com) does the swiping and dragging,
so it moves like a native app, not a 2009 slideshow.

The arrows sit just outside the slides, so leave room around the carousel
(`px-12`). On narrow screens, add `static` and put them in a row of their own,
like the previews.

## Sizes [#sizes]

Items are full width by default. Change it with `basis-*`, responsive classes
included.

```tsx
<Carousel opts={{ align: 'start' }}>
  <CarouselContent>
    <CarouselItem className="basis-1/2 sm:basis-1/3">...</CarouselItem>
  </CarouselContent>
</Carousel>
```

## Spacing [#spacing]

The gap is a start padding on `CarouselItem` (`ps-4`) and a matching negative
margin on `CarouselContent` (`-ms-4`). Change both together. Both are logical,
so RTL gets the gap on the right side.

```tsx
<CarouselContent className="-ms-2 md:-ms-4">
  <CarouselItem className="ps-2 md:ps-4">...</CarouselItem>
</CarouselContent>
```

## Vertical [#vertical]

`orientation="vertical"` scrolls up and down. Give `CarouselContent` a fixed
height and space with `-mt-*` / `pt-*`.

```tsx
<Carousel orientation="vertical" opts={{ align: 'start' }}>
  <CarouselContent className="-mt-2 h-48">
    <CarouselItem className="basis-1/2 pt-2">...</CarouselItem>
  </CarouselContent>
</Carousel>
```

## Options [#options]

`opts` goes straight to Embla: `loop` for an endless ride, `align` to snap to
`start`, `center` or `end`, `dragFree` for free scrolling.

```tsx
<Carousel opts={{ align: 'start', loop: true }}>...</Carousel>
```

On a right-to-left page, tell Embla too. The layout flips by itself, but the
scroll math needs the hint:

```tsx
<Carousel dir="rtl" opts={{ direction: 'rtl' }}>
```

## API [#api]

`setApi` hands you the Embla instance for custom controls, like the dots in the
preview.

```tsx
import type { CarouselApi } from '@vitnode/core/components/ui/carousel'

const [api, setApi] = React.useState<CarouselApi>()
const [current, setCurrent] = React.useState(0)

React.useEffect(() => {
  if (!api) return

const onSelect = () => {
    setCurrent(api.selectedScrollSnap())
  }

api.on('select', onSelect)

return () => {
    api.off('select', onSelect)
  }
}, [api])

<Carousel setApi={setApi}>...</Carousel>
```

`api.scrollTo(index)` is all a dot button needs. Inside the carousel,
`useCarousel()` returns `api`, `scrollPrev`, `scrollNext`, `canScrollPrev` and
`canScrollNext`.

## Plugins [#plugins]

Pass Embla plugins through `plugins`, for example autoplay:

```bash tab="bun"
bun i embla-carousel-autoplay
```

```bash tab="pnpm"
pnpm i embla-carousel-autoplay
```

```bash tab="npm"
npm i embla-carousel-autoplay
```

</Tabs>

```tsx
import Autoplay from 'embla-carousel-autoplay'

<Carousel plugins={[Autoplay({ delay: 4000, stopOnInteraction: true })]}>
```

Keep `stopOnInteraction` on, and skip autoplay under reduced motion. Nobody
likes chasing a runaway slide.

## Accessibility [#accessibility]

- The root is a `region` with `aria-roledescription="carousel"`. Give it an
  `aria-label`.
- Each slide is a `group` with `aria-roledescription="slide"`. Add a label like
  `aria-label="2 of 5"`.
- The arrows have translated "Previous" / "Next" labels and disable at the ends.
- With focus inside, arrow keys change slides: left/right when horizontal,
  up/down when vertical. In RTL (`dir="rtl"` or `opts.direction`), left and
  right follow the reading direction.
- Text fields keep their arrow keys, and so does any child that handled the key.
- Under reduced motion, slides change instantly instead of gliding.

## Props [#props]

`CarouselPrevious` and `CarouselNext` take every [Button](/docs/ui/button) prop
and default to `variant="outline"` and `size="icon-sm"`.

## API Reference [#api-reference]

[Embla Carousel - API](https://www.embla-carousel.com/api/)

# Cascader (/docs/ui/cascader)

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormCascader } from '@vitnode/core/components/form/fields/cascader'

const formSchema = z.object({
  office: z.string({ error: 'Pick an office to continue' }),
  backupOffice: z.string().optional(),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'office',
      component: (props) => (
        <AutoFormCascader
          {...props}
          label="Office"
          options={locations}
          searchable
        />
      ),
    },
  ]}
/>
```

The form stores the **picked leaf's value** (`"krakow"`), not the path. Optional
fields get a clear button automatically.

</Tab>

```tsx
import { Cascader } from '@vitnode/core/components/ui/cascader'

const [office, setOffice] = React.useState<string | null>(null)

<Cascader
  aria-labelledby="office-label"
  onValueChange={setOffice}
  options={locations}
  value={office}
/>
```

</Tab>
</Tabs>

## Options [#options]

A plain tree. An option with `children` is a branch that opens the next level;
one without is a pickable leaf.

```ts
import type { CascaderOption } from '@vitnode/core/components/ui/cascader'

const locations: CascaderOption[] = [
  {
    label: 'Europe',
    value: 'europe',
    children: [
      {
        label: 'Poland',
        value: 'poland',
        children: [
          { label: 'Warsaw', value: 'warsaw' },
          { label: 'Kraków', value: 'krakow' },
        ],
      },
      { label: 'Iceland', value: 'iceland', disabled: true },
    ],
  },
]
```

Need "Europe / Poland" too? `onValueChange` also gets the full path:

```tsx
<Cascader
  onValueChange={(value, path) => setTrail(path.map((option) => option.label))}
  options={locations}
/>
```

## Search [#search]

`searchable` adds a box that searches every leaf at once. Type "krak" in the
preview and "Europe / Poland / Kraków" is one click away. Accents don't matter:
"sao" finds São Paulo.

## Columns [#columns]

By default a branch **replaces the list** with its children, with a back button
on top. The popup stays the field's width.

`layout="columns"` shows each level in a new column, and the popup widens to
fit. Add `expandTrigger="hover"` to open branches on hover. Phones always drill
down: there's no room for columns at 375px.

```tsx
<Cascader expandTrigger="hover" layout="columns" options={locations} />
```

Levels slide in from the direction you moved. The popup's height (drill) or
width (columns) animates with them, mirrored in RTL. Reduced motion switches
everything instantly.

## Accessibility [#accessibility]

- Each level is a keyboard listbox: <kbd>↑</kbd> <kbd>↓</kbd> move,
  <kbd>→</kbd> (<kbd>←</kbd> in RTL) or <kbd>Enter</kbd> opens a branch,
  <kbd>←</kbd> goes back, <kbd>Home</kbd> / <kbd>End</kbd> jump,
  <kbd>Escape</kbd> closes.
- Branches announce whether they're open, and the picked path is marked
  selected.
- Label it. `AutoFormCascader` does it for you; a standalone `Cascader` needs
  `aria-labelledby`.

## Props [#props]

<TypeTable
  type={{
    options: {
      description: 'The tree of options.',
      type: 'CascaderOption[]',
      required: true,
    },
    value: {
      description: 'Picked leaf value (controlled).',
      type: 'string | null',
    },
    defaultValue: {
      description: 'Starting value when uncontrolled.',
      type: 'string | null',
      default: 'null',
    },
    onValueChange: {
      description: 'Called with the leaf value and its full path.',
      type: '(value: string | null, path: CascaderOption[]) => void',
    },
    searchable: {
      description: 'Adds a search box across every leaf.',
      type: 'boolean',
      default: 'false',
    },
    layout: {
      description: 'One level at a time, or every level side by side.',
      type: '"drill" | "columns"',
      default: '"drill"',
    },
    expandTrigger: {
      description: 'Columns layout: open branches on click or on hover.',
      type: '"click" | "hover"',
      default: '"click"',
    },
    showClear: {
      description:
        'Shows a clear button. AutoForm turns it on for optional fields.',
      type: 'boolean',
      default: 'false',
    },
    separator: {
      description: 'Between labels in the trigger and search results.',
      type: 'string',
      default: '" / "',
    },
    placeholder: {
      description: 'Shown while nothing is picked.',
      type: 'string',
      default: '"Select an option"',
    },
    disabled: {
      description: 'Disables the trigger.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

# Chart (/docs/ui/chart)

## Installation [#installation]

You write plain [TanStack Charts](https://tanstack.com/charts) and borrow the
container, colors, tooltip and legend from VitNode. Every TanStack mark, scale
and transform works out of the box.

```bash tab="bun"
bun i @tanstack/charts
```

```bash tab="pnpm"
pnpm i @tanstack/charts
```

```bash tab="npm"
npm i @tanstack/charts
```

</Tabs>

## Create a bar chart [#create-a-bar-chart]

A chart is a **definition** (marks, scales, colors) rendered by TanStack's
`Chart` inside VitNode's `ChartContainer`.

```tsx
import type { ChartConfig } from '@vitnode/core/components/ui/chart'

import { barY, defineChart, group } from '@tanstack/charts'
import { Chart } from '@tanstack/charts/react/tooltip'
import { scaleBand } from '@tanstack/charts/scales/band'
import { scaleLinear } from '@tanstack/charts/scales/linear'
import { tooltip } from '@tanstack/charts/tooltip'
import { fold } from '@tanstack/charts/transform/fold'
import {
  ChartContainer,
  ChartLegend,
  ChartTooltipContent,
} from '@vitnode/core/components/ui/chart'
import { chartColor } from '@vitnode/core/components/ui/chart-utils'

const chartData = [
  { month: 'January', desktop: 186, mobile: 80 },
  { month: 'February', desktop: 305, mobile: 200 },
]

const chartConfig = {
  desktop: { label: 'Desktop', color: 'var(--chart-1)' },
  mobile: { label: 'Mobile', color: 'var(--chart-2)' },
} satisfies ChartConfig

// One row per bar: { month, device: 'desktop' | 'mobile', visitors }
const rows = fold(chartData, {
  fields: ['desktop', 'mobile'] as const,
  as: { key: 'device', value: 'visitors' },
})

const definition = defineChart({
  marks: [
    barY(rows, {
      x: 'month',
      y: 'visitors',
      color: 'device',
      layout: group(),
      radius: 4,
    }),
  ],
  scales: {
    x: { scale: () => scaleBand().padding(0.2) },
    y: { scale: scaleLinear, nice: true, grid: true, axis: false },
  },
  color: chartColor(chartConfig),
  focus: 'group-x',
  tooltip,
})

export const VisitorsChart = () => (
  <ChartContainer config={chartConfig}>
    <Chart
      ariaLabel="Visitors"
      definition={definition}
      height={280}
      renderTooltipBody={({ points }) => (
        <ChartTooltipContent points={points} />
      )}
    />
    <ChartLegend />
  </ChartContainer>
)
```

- `fold()` turns wide rows into one row per series. TanStack Charts colors and
  groups marks by a field, so the series name has to live in the data.
- `color: 'device'` sends each row through `chartColor(chartConfig)`, which
  paints `desktop` with `--color-desktop`.
- Import `Chart` from `@tanstack/charts/react/tooltip` whenever you pass
  `renderTooltipBody`. The plain `@tanstack/charts/react` entry keeps
  TanStack's built-in tooltip text.

Define charts at module scope. When a definition reads props or state, wrap
it in `useMemo`. A new definition object tells TanStack Charts to redraw.

## Chart config [#chart-config]

Each config key matches a series value (`desktop`, `mobile`) or a category
(`general`, `support`). The config holds the words and colors, so your data
stays clean.

```tsx
const chartConfig = {
  desktop: { label: 'Desktop', icon: Monitor, color: 'var(--chart-1)' },
  mobile: {
    label: 'Mobile',
    theme: { light: 'var(--chart-2)', dark: 'var(--chart-4)' },
  },
} satisfies ChartConfig
```

- `label` is what the tooltip and legend show.
- `icon` replaces the color swatch in the tooltip and legend.
- `color` works in both themes. Use `theme` when light and dark need different
  colors.

## Colors [#colors]

For every config key, `ChartContainer` creates a `--color-<key>` variable
scoped to that chart. There are two ways to use it:

```tsx
// Map a field to colors - the legend and tooltip swatches follow
barY(rows, { x: 'month', y: 'visitors', color: 'device' })
defineChart({ marks, scales, color: chartColor(chartConfig) })

// Or paint one mark directly
lineY(chartData, {
  x: 'day',
  y: 'responseTime',
  stroke: 'var(--color-responseTime)',
})
```

`ChartContainer` also maps TanStack's default palette to `--chart-1` to
`--chart-5`, and styles axes, grid lines, focus rings and tooltips with
VitNode tokens. Charts follow light and dark mode without extra code.

Pick from `--chart-1` to `--chart-5` in order: blue, orange, gray, green, red.
Two or three per chart is plenty. See [Colors](/docs/ui/colors#chart-palette).

## Area chart [#area-chart]

Stack the rows with `stackRowsY()`, then draw an area and a line from the same
endpoints. Gradients are chart resources, so they can read the color variables.

```tsx
import { areaY, defineChart, lineY } from '@tanstack/charts'
import { d3Curve } from '@tanstack/charts/d3/shape'
import { decorative } from '@tanstack/charts/mark/decorative'
import { stackRowsY } from '@tanstack/charts/transform/stack'
import { curveMonotoneX } from 'd3-shape'

const curve = d3Curve(curveMonotoneX)

const rows = stackRowsY(
  fold(chartData, {
    fields: ['upgrades', 'downloads'] as const,
    as: { key: 'kind', value: 'installs' },
  }),
  { x: 'month', y: 'installs', z: 'kind' },
)

const definition = defineChart({
  marks: [
    decorative(
      areaY(rows, {
        x: 'month',
        y1: 'y1',
        y2: 'y2',
        z: 'kind',
        fill: (row) => `url(#fill-${row.kind})`,
        fillOpacity: 1,
        curve,
      }),
    ),
    lineY(rows, { x: 'month', y: 'y2', z: 'kind', curve }),
  ],
  scales: {
    x: { scale: scalePoint },
    y: { scale: scaleLinear, nice: true, grid: true, axis: false },
  },
  color: chartColor(chartConfig),
  gradients: (['downloads', 'upgrades'] as const).map((kind) => ({
    id: `fill-${kind}`,
    y1: 0,
    y2: 1,
    stops: [
      { offset: 0.05, color: `var(--color-${kind})`, opacity: 0.8 },
      { offset: 0.95, color: `var(--color-${kind})`, opacity: 0.1 },
    ],
  })),
  focus: 'group-x',
  tooltip,
})
```

- `decorative()` keeps the area visible but out of hover and keyboard focus,
  so every month shows up in the tooltip once.
- The line sits on the stacked top (`y2`). Pass `valueKey="installs"` to the
  tooltip so it shows each series' own value, not the running total.
- Smooth curves come from `d3-shape`. Install it next to `@tanstack/charts`
  when you want them. Straight segments need nothing extra.

## Line chart [#line-chart]

```tsx
import { crosshair } from '@tanstack/charts/crosshair'

const definition = defineChart({
  marks: [
    crosshair({ x: true, y: false }),
    lineY(chartData, {
      x: 'day',
      y: 'responseTime',
      stroke: 'var(--color-responseTime)',
      points: true,
    }),
  ],
  scales: {
    x: { scale: () => scalePoint().padding(0.3) },
    y: { scale: scaleLinear, nice: true, grid: true, axis: false },
  },
  focus: 'nearest-x',
  maxFocusDistance: Number.POSITIVE_INFINITY,
  tooltip,
})
```

`focus: 'nearest-x'` with an infinite distance snaps to the closest day
anywhere in the plot, and `crosshair()` draws a guide at that day. A single
series has no series field, so name it in the tooltip with
`nameKey="responseTime"`.

## Pie chart [#pie-chart]

Each slice is a row, not a series. `pie()` turns totals into angles, and
`radialArc()` draws them inside `polar()`.

```tsx
import { pie, polar, radialArc } from '@tanstack/charts/polar'

const definition = defineChart({
  marks: [
    polar({
      marks: [
        radialArc(pie(chartData, { value: 'threads' }), {
          innerRadius: ({ radius }) => radius * 0.5,
          color: 'category',
          key: 'category',
        }),
      ],
      scales: { angle: null, radius: null },
    }),
  ],
  scales: { x: null, y: null },
  color: chartColor(chartConfig),
  tooltip,
})

<ChartTooltipContent hideLabel nameKey="category" points={points} valueKey="threads" />
```

Return `0` from `innerRadius` for a full pie instead of a donut.

## Tooltip [#tooltip]

`ChartTooltipContent` renders inside TanStack's tooltip and reads labels, icons
and colors from your config. Hover the previews to compare `dashed` (bar),
`dot` (area) and `line` (line).

```tsx
<Chart
  ariaLabel="Visitors"
  definition={definition}
  renderTooltipBody={({ points }) => (
    <ChartTooltipContent indicator="line" points={points} />
  )}
/>
```

<TypeTable
  type={{
    points: {
      description: 'Focused points from renderTooltipBody.',
      type: 'readonly ChartPoint[]',
      required: true,
    },
    indicator: {
      description: 'Shape next to each value.',
      type: "'dot' | 'line' | 'dashed'",
      default: "'dot'",
    },
    hideLabel: {
      description: 'Hides the heading, such as the month.',
      type: 'boolean',
      default: 'false',
    },
    hideIndicator: {
      description: 'Hides the indicator shape.',
      type: 'boolean',
      default: 'false',
    },
    labelKey: {
      description: 'Data field for the heading. Defaults to the x value.',
      type: 'string',
    },
    nameKey: {
      description:
        'Data field (or config key) for each value name. Defaults to the series.',
      type: 'string',
    },
    valueKey: {
      description: 'Data field for each value. Defaults to the y value.',
      type: 'string',
    },
    labelFormatter: {
      description: 'Formats the heading.',
      type: '(label, points) => ReactNode',
    },
    formatter: {
      description: 'Renders each row yourself.',
      type: '(value, name, point, index) => ReactNode',
    },
  }}
/>

Placement and behavior live in the definition. A few useful options:

- `focus: 'group-x'` shows every series at the hovered category.
- `tooltip: { use: tooltip, sort: 'color-domain' }` lists rows in config order.
- `tooltip: { use: tooltip, portal }` (from `@tanstack/charts/tooltip/portal`)
  lets the tooltip escape a card with `overflow: hidden`.

Click or press <kbd>Enter</kbd> to pin a tooltip, <kbd>Esc</kbd> to unpin it.

## Legend [#legend]

`ChartLegend` is a plain HTML list built from your config, so screen readers
can read it. Put it inside `ChartContainer`, after the chart.

```tsx
<ChartContainer config={chartConfig}>
  <Chart ariaLabel="Threads by category" definition={definition} />
  <ChartLegend />
</ChartContainer>
```

## Size [#size]

`Chart` fills the container's width. Set its height with one of:

- `height={280}` - a fixed height, the safest choice for dashboards.
- `aspectRatio={16 / 9}` - height follows the width.

Charts render on the server at `initialWidth` (640px by default), then measure
their real width after hydration.

## Animation [#animation]

Out of the box a chart paints its final state at once. `svgAnimation: true` in
the definition tweens later data updates, like switching a date range.

Want bars that grow and pies that sweep in? Swap `Chart` for `RendererChart`
and hand it the `motion()` renderer:

```tsx
import { motion } from '@tanstack/charts/motion'
import { RendererChart } from '@tanstack/charts/react/tooltip'
import { chartTooltipMotion } from '@vitnode/core/components/ui/chart-utils'

const renderer = motion({
  transition: { type: 'tween', duration: 700, easing: 'ease-out' },
})

const definition = defineChart({
  marks,
  scales,
  tooltip: { use: tooltip, motion: chartTooltipMotion },
})

<ChartContainer config={chartConfig}>
  <RendererChart
    ariaLabel="Visitors"
    definition={definition}
    height={280}
    renderer={renderer}
    renderTooltipBody={({ points }) => <ChartTooltipContent points={points} />}
  />
</ChartContainer>
```

- The entrance plays when the chart mounts in the browser. A server-rendered
  chart skips it, so it never flashes the final bars first. To animate a chart
  below the fold, mount it when it scrolls into view with
  `useIntersectionObserver`, like the demos on this page.
- `chartTooltipMotion` is a quick spring with no bounce. The tooltip fades in,
  glides from point to point and fades out. Give a `crosshair` the same
  spring (`motion: { transition: chartTooltipMotion }`) so the guide and the
  tooltip move together.
- A plain `Chart` keeps the tooltip instant: tooltip motion needs `motion()`.
- `motion()` respects `prefers-reduced-motion` and simply paints the final
  state.

## Accessibility [#accessibility]

- `ariaLabel` is required. Add `ariaDescription` for a sentence about the data.
- Tab to the chart, then use the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd>
  to move between points. The tooltip follows the keyboard.
- Keep a visible heading next to the chart, like a `CardTitle`. Never rely on
  color alone: tooltip and legend labels tell series apart.
- Every animation respects `prefers-reduced-motion`.

## Migrate from Recharts [#migrate-from-recharts]

VitNode used Recharts before. The ideas map one to one:

| Recharts                                    | TanStack Charts                                        |
| ------------------------------------------- | ------------------------------------------------------ |
| `<BarChart>` + `<Bar>` children             | `defineChart({ marks: [barY(...)] })`                  |
| Wide rows + one `dataKey` per series        | `fold()` into long rows + `color: 'series'`            |
| `fill="var(--color-desktop)"` on each `Bar` | `color: chartColor(chartConfig)`                       |
| `stackId`                                   | Repeated x values stack by default, or `stackRowsY()`  |
| `<XAxis>` / `<CartesianGrid>`               | `scales.x.axis` / `scales.y.grid`                      |
| `type="monotone"`                           | `curve: d3Curve(curveMonotoneX)`                       |
| `<ChartTooltip content={...} />`            | `tooltip` in the definition + `renderTooltipBody`      |
| `<ChartLegend content={...} />`             | `<ChartLegend />`                                      |
| `accessibilityLayer`, `title`, `desc`       | `ariaLabel`, `ariaDescription` (keyboard is always on) |
| `ChartContainer className="aspect-video"`   | `<Chart height={280} />` or `aspectRatio={16 / 9}`     |

`ChartTooltip` and `ChartLegendContent` are gone: the tooltip is configured in
the definition, and `ChartLegend` is now a component you render directly.

## API Reference [#api-reference]

- [TanStack Charts - React adapter](https://tanstack.com/charts/latest/docs/framework/react/adapter)
- [TanStack Charts - Example gallery](https://tanstack.com/charts/latest/docs/examples/index)

# Checkbox (/docs/ui/checkbox)

## Preview [#preview]

## Usage [#usage]

```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormCheckbox } from '@vitnode/core/components/form/fields/checkbox'
import { z } from 'zod'

const formSchema = z.object({
  acceptRules: z.boolean().refine((value) => value, {
    message: 'You need to accept the rules to join',
  }),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'acceptRules',
      component: (props) => (
        <AutoFormCheckbox {...props} label="I accept the community rules" />
      ),
    },
  ]}
/>
```

</Tab>
  <Tab value="Manual">

```tsx
import { Checkbox } from '@vitnode/core/components/ui/checkbox'
import { Label } from '@vitnode/core/components/ui/label'
```

```tsx
<Label>
  <Checkbox checked={checked} onCheckedChange={setChecked} />
  Pin this thread
</Label>
```

</Tab>
</Tabs>

## States [#states]

- `indeterminate` draws a dash, for "some selected".
- `disabled` dims it. Add `data-disabled` to the parent [Field](/docs/ui/field)
  to dim the label too.
- `aria-invalid` turns it red. Point `aria-describedby` at the error.

```tsx
<Field data-invalid orientation="horizontal">
  <Checkbox aria-describedby="rules-error" aria-invalid id="rules" />
  <FieldContent>
    <FieldLabel htmlFor="rules">I have read the community rules</FieldLabel>
    <FieldError id="rules-error">Tick this one to post.</FieldError>
  </FieldContent>
</Field>
```

Every checkbox needs a label. The hit area reaches beyond the box, so it's
easy to tap on a phone.

## Props [#props]

`AutoFormCheckbox` also accepts every [Base UI Checkbox](https://base-ui.com/react/components/checkbox#api-reference) prop.

## API Reference [#api-reference]

[Base UI - Checkbox](https://base-ui.com/react/components/checkbox#api-reference)

# Color (/docs/ui/color)

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormColor } from '@vitnode/core/components/form/fields/color'
```

```tsx
const formSchema = z.object({
  color: z.string().default('hsl(215, 81%, 52%)'),
})

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'color',
      component: props => <AutoFormColor {...props} label="Category color" />,
    },
  ]}
/>
```

</Tab>

```ts
import { ColorPicker } from '@vitnode/core/components/ui/color-picker'
```

```tsx
const [color, setColor] = React.useState('hsl(215, 81%, 52%)')

<ColorPicker onChange={setColor} value={color} />
```

`ColorPicker` is controlled: `onChange` gets the new color string.

</Tab>
</Tabs>

## Preset palette [#preset-palette]

A default swatch plus seven hues and gray, in up to three tones. The default
stores `""` and renders in the theme's text color. Every tone keeps 3:1
contrast on light and dark backgrounds, and a unit test enforces it.

For the palette alone, use `ColorPresetPicker`. The values live in
`@vitnode/core/components/ui/color-presets`.

```ts
import { ColorPresetPicker } from '@vitnode/core/components/ui/color-preset-picker'
```

```tsx
<ColorPresetPicker onChange={setColor} value={color} />
```

The swatches are one radio group, so arrow keys move between them.

## Output format [#output-format]

Presets and the picker store HSL, like `hsl(215, 81%, 52%)`. The text input
stores any CSS color you type. Hex, `rgb()`, `hsl()` and `oklch()` move the
picker; anything else parks it on black.

[react-colorful](https://github.com/omgovich/react-colorful) loads only when the
popover opens.

## Clearing [#clearing]

`allowRemoveColor` adds a "Remove" button that sets `""`. The
[preview](#preview) has it on.

## Editor text color [#editor-text-color]

The [editor](/docs/ui/editor)'s text color action uses the same preset palette,
with no free-form picker. Its popover ends with a "Remove color" button.

## Props [#props]

Other props, like `disabled`, go to the trigger button.

# Colors (/docs/ui/colors)

Colors are **semantic tokens**: they name a job (`card`, `primary`), not a hue,
so every component follows your theme and dark mode for free. Flip the theme
and watch the values below change.

## Tokens [#tokens]

Each token is a CSS variable in `src/styles.css` and a Tailwind color:
`bg-card`, `text-card-foreground`, `border-input`. Click a swatch's copy button
to grab its class.

## Written in OKLCH [#written-in-oklch]

```css
--primary: oklch(0.52 0.2 264);
```

| `L` Lightness         | `C` Chroma               | `H` Hue                             |
| --------------------- | ------------------------ | ----------------------------------- |
| `0` black - `1` white | `0` gray - `~0.37` vivid | `27` red · `155` green · `264` blue |

Same `L` means the same perceived brightness, so contrast is predictable: tune
`L` for readability, keep `H` for brand.

## Surfaces stack [#surfaces-stack]

`background` → `card` → `popover`. In dark mode each layer gets lighter as it
rises. Always pair a surface with its `-foreground` text.

```tsx
<div className="bg-card text-card-foreground rounded-lg border p-4">
  <p className="text-muted-foreground">3 drafts waiting for review</p>
</div>
```

## Status [#status]

Status colors have no `-foreground`. Use them as text on a soft tint of
themselves, or let the component pick for you.

```tsx
<span className="bg-success/10 text-success dark:bg-success/20 rounded-md px-2 py-1 text-sm">
  Published
</span>
```

## Chart palette [#chart-palette]

Use `chart-1` to `chart-5` in order: blue, orange, gray, green, red. Green and
red are never neighbors and differ in lightness, so they stay apart for
color-blind readers.

```ts
const chartConfig = {
  posts: { label: 'Posts', color: 'var(--chart-1)' },
  replies: { label: 'Replies', color: 'var(--chart-2)' },
}
```

## Do and don't [#do-and-dont]

- Keep a screen to 3-5 colors: neutrals, primary and one status.
- Never use purple prominently, and never change `--primary`. VitNode blue
  stays blue.
- Filled `primary` is for short labels. Its dark-mode contrast is too low for
  paragraphs.

## Related [#related]

# Combobox (/docs/ui/combobox)

## Preview [#preview]

## Usage [#usage]

Options come from the `z.enum`. `labels` gives each value a readable name.

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormCombobox } from '@vitnode/core/components/form/fields/combobox'

const formSchema = z.object({
  category: z.enum(['general', 'support']),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'category',
      component: (props) => (
        <AutoFormCombobox
          {...props}
          label="Category"
          labels={[
            { value: 'general', label: 'General discussion' },
            { value: 'support', label: 'Help & support' },
          ]}
        />
      ),
    },
  ]}
/>
```

</Tab>

```tsx
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
} from '@vitnode/core/components/ui/combobox'

const categories = ['General', 'Support', 'Showcase']

;<Combobox items={categories}>
  <ComboboxInput placeholder="Pick a category" />
  <ComboboxContent>
    <ComboboxEmpty>No categories found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

</Tab>
</Tabs>

## Groups and clear button [#groups-and-clear-button]

Give options a `group` to sort them under headings. Groups follow the order they
first appear in `labels`; ungrouped options sit at the top. `showClear` adds an
× that empties the field.

```tsx
<AutoFormCombobox
  {...props}
  labels={[
    { group: 'Europe', label: 'Warsaw', value: 'europe-warsaw' },
    { group: 'Americas', label: 'New York', value: 'america-new-york' },
  ]}
  showClear
/>
```

## Async search [#async-search]

`fetchData` loads options from your API as people type (debounced by 500ms). It
needs a stable `id` and a `queryKey` for caching. Each picked value is a
`{ value, label }` object, not a string.

```tsx
import { fetcher } from '@vitnode/core/tanstack/fetcher'

const formSchema = z.object({
  moderators: z
    .array(z.object({ value: z.string(), label: z.string() }))
    .min(1)
    .default([]),
})

;<AutoFormCombobox
  {...props}
  fetchData={async ({ search }) => {
    const res = await fetcher({
      plugin: '@acme/forum',
      method: 'get',
      module: 'members',
      path: '/',
      args: { query: { search } },
    })
    const data = await res.json()

return data.edges.map((member) => ({
      label: member.name,
      value: member.id.toString(),
    }))
  }}
  id="moderators"
  multiple
  queryKey={['forum', 'members']}
  renderItem={(item) => <UserRow name={item.label} />}
  searchPlaceholder="Find a member..."
/>
```

`renderItem` customizes each async option, like adding an avatar.

## Multiple [#multiple]

Add `multiple` and use an array in the schema. Picks become chips, and the box
wraps when full. `.min()` and `.max()` on the array become the validation
messages.

```ts
const formSchema = z.object({
  topics: z
    .array(z.enum(['news', 'guides', 'releases']))
    .min(1, 'Pick at least one topic')
    .max(3, 'Three topics is plenty'),
})
```

```tsx
<AutoFormCombobox {...props} labels={topics} maxVisibleChips={3} multiple />
```

- `maxVisibleChips` shows the first few chips plus "+N more". Every pick is
  still saved.
- `renderChip` customizes each chip.
- <kbd>Backspace</kbd> in an empty search removes the last chip.
  <kbd>Escape</kbd> with the list closed clears every pick, so mind that second
  Escape.
- Reduced motion turns off the chip and chevron animations.

For a manual multi-select, wrap chips in `ComboboxChips` and anchor the popup to
it:

```tsx
const anchor = useComboboxAnchor()

;<Combobox items={frameworks} multiple>
  <ComboboxChips ref={anchor}>
    <ComboboxValue>
      {(values: string[]) => (
        <>
          {values.map((value) => (
            <ComboboxChip key={value}>{value}</ComboboxChip>
          ))}
          <ComboboxChipsInput placeholder="Add a framework" />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxContent anchor={anchor}>
    <ComboboxList>
      {(item) => (
        <ComboboxItem key={item} value={item}>
          {item}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

## Props [#props]

<TypeTable
  type={{
    label: {
      description: 'Shown above the input.',
      type: 'ReactNode',
    },
    description: {
      description: 'Shown below the input.',
      type: 'ReactNode',
    },
    labels: {
      description: 'Readable label and optional group for each enum value.',
      type: '{ value: string; label: string; group?: string }[]',
      default: '[]',
    },
    placeholder: {
      description: 'Input placeholder.',
      type: 'string',
      default: '"Select an option"',
    },
    fetchData: {
      description:
        'Loads options for the search text. Turns on async search and requires `id` and `queryKey`.',
      type: '({ search }) => { value: string; label: string }[] | Promise<...>',
    },
    id: {
      description: 'Stable id. Required with `fetchData`.',
      type: 'string',
    },
    queryKey: {
      description:
        'TanStack Query key prefix for cached results. Required with `fetchData`.',
      type: 'readonly unknown[]',
    },
    searchPlaceholder: {
      description:
        'Input placeholder with `fetchData`. Falls back to `placeholder`.',
      type: 'string',
    },
    renderItem: {
      description: 'Custom content for each `fetchData` option.',
      type: '(item: { value: string; label: string }) => ReactNode',
    },
    multiple: {
      description: 'Allows many picks, shown as chips. Works with `fetchData`.',
      type: 'boolean',
      default: 'false',
    },
    maxVisibleChips: {
      description: 'With `multiple`, shows this many chips plus "+N more".',
      type: 'number',
    },
    renderChip: {
      description: 'With `multiple`, custom content for each chip.',
      type: '(item: { value: string; label: string }) => ReactNode',
    },
    showClear: {
      description: 'Single select only. Shows a button that clears the value.',
      type: 'boolean',
      default: 'false',
    },
    disabled: {
      description: 'Disables the combobox.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

# Command (/docs/ui/command)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Command,
  CommandEmpty,
  CommandGroup,
  CommandInput,
  CommandItem,
  CommandList,
  CommandSeparator,
  CommandShortcut,
} from '@vitnode/core/components/ui/command'
```

```tsx
<Command>
  <CommandInput placeholder="Type a command or search..." />
  <CommandList>
    <CommandEmpty>No results found.</CommandEmpty>
    <CommandGroup heading="Suggestions">
      <CommandItem>Calendar</CommandItem>
      <CommandItem>Search Emoji</CommandItem>
    </CommandGroup>
  </CommandList>
</Command>
```

Type and the list filters itself, best matches first. Empty groups hide. Built
on [cmdk](https://cmdk.paco.me), so every cmdk prop works.

## Groups, icons and shortcuts [#groups-icons-and-shortcuts]

`CommandGroup` takes a `heading`, and `CommandSeparator` splits groups. Icons go
first and are sized for you. `CommandShortcut` is only a label: bind the keys
yourself.

```tsx
<CommandGroup heading="Settings">
  <CommandItem>
    <UserIcon />
    <span>Profile</span>
    <CommandShortcut>⌘P</CommandShortcut>
  </CommandItem>
</CommandGroup>
<CommandSeparator />
```

`CommandEmpty` shows only when nothing matches. Make it kind.

## Selecting items [#selecting-items]

`onSelect` fires on click and <kbd>Enter</kbd>. `disabled` keeps an item
visible but skipped. Items match by their text: add `value` when the text isn't
unique, and `keywords` for other names people might type.

```tsx
<CommandItem onSelect={() => router.navigate({ to: '/settings' })}>
  Settings
</CommandItem>
<CommandItem keywords={['theme', 'night']} value="toggle-dark-mode">
  Toggle dark mode
</CommandItem>
```

## Dialog [#dialog]

`CommandDialog` wraps a `Command` in a [Dialog](/docs/ui/dialog) with a
screen-reader-only title and description. Control it with `open` and
`onOpenChange`, and bind a shortcut yourself.

```tsx
const [open, setOpen] = React.useState(false)

React.useEffect(() => {
  const handleKeyDown = (event: KeyboardEvent) => {
    if (event.key.toLowerCase() !== 'j') return
    if (!event.metaKey && !event.ctrlKey) return
    if (event.altKey || event.shiftKey || event.defaultPrevented) return

event.preventDefault()
    setOpen(prev => !prev)
  }

window.addEventListener('keydown', handleKeyDown)

return () => window.removeEventListener('keydown', handleKeyDown)
}, [])

<CommandDialog onOpenChange={setOpen} open={open}>
  <Command>
    <CommandInput placeholder="What do you need?" />
    <CommandList>...</CommandList>
  </Command>
</CommandDialog>
```

<Callout title="Why ⌘J and not ⌘K?">
  The docs search and the AdminCP already own <kbd>⌘K</kbd> / <kbd>Ctrl+K</kbd>,
  so the demo uses <kbd>⌘J</kbd> / <kbd>Ctrl+J</kbd>. Pick a free key and remove
  the listener on unmount. Inside the open palette <kbd>Ctrl+J</kbd> moves down
  a row, so <kbd>Escape</kbd> is the way out.
</Callout>

Show the shortcut next to the trigger with [`Kbd`](/docs/ui/kbd), like the demo.

## Your own filtering [#your-own-filtering]

Searching an API? Set `shouldFilter={false}` and render what your query returns.
The AdminCP search works this way.

```tsx
<Command label="Search members" shouldFilter={false}>
  <CommandInput onValueChange={setSearch} value={search} />
  <CommandList>
    {members.map((member) => (
      <CommandItem key={member.id} value={member.id}>
        {member.name}
      </CommandItem>
    ))}
  </CommandList>
</Command>
```

## Accessibility [#accessibility]

- The input is a `combobox` and the list a `listbox`, so screen readers announce
  the highlighted option.
- <kbd>↑</kbd> / <kbd>↓</kbd> move, <kbd>Home</kbd> / <kbd>End</kbd> jump to the
  ends, <kbd>Enter</kbd> selects. `loop` wraps at the edges.
- <kbd>Ctrl+N</kbd> / <kbd>Ctrl+J</kbd> and <kbd>Ctrl+P</kbd> /<kbd>Ctrl+K</kbd>
  also move. Turn them off with `vimBindings={false}`.
- Give a standalone `Command` a `label` so the input has a name.
  `CommandDialog` traps focus and closes on <kbd>Escape</kbd>.

## Props [#props]

### Command [#command]

<TypeTable
  type={{
    label: {
      description: 'Accessible label for the command menu input.',
      type: 'string',
    },
    shouldFilter: {
      description:
        'Turn off the built-in filtering and sorting when you filter the items yourself.',
      type: 'boolean',
      default: 'true',
    },
    filter: {
      description:
        'Custom ranking function. Return `0` to hide an item and a higher number to rank it higher.',
      type: '(value: string, search: string, keywords?: string[]) => number',
    },
    value: {
      description: 'Controls the highlighted item.',
      type: 'string',
    },
    onValueChange: {
      description: 'Called when the highlighted item changes.',
      type: '(value: string) => void',
    },
    loop: {
      description: 'Wrap the keyboard selection around at the top and bottom.',
      type: 'boolean',
      default: 'false',
    },
    vimBindings: {
      description: 'Enable the `Ctrl+N/J/P/K` navigation shortcuts.',
      type: 'boolean',
      default: 'true',
    },
  }}
/>

### CommandDialog [#commanddialog]

<TypeTable
  type={{
    open: {
      description: 'Controls whether the dialog is open.',
      type: 'boolean',
    },
    onOpenChange: {
      description: 'Called when the dialog opens or closes.',
      type: '(open: boolean) => void',
    },
    title: {
      description: 'Screen-reader-only dialog title.',
      type: 'string',
      default: '"Command Palette"',
    },
    description: {
      description: 'Screen-reader-only dialog description.',
      type: 'string',
      default: '"Search for a command to run..."',
    },
    showCloseButton: {
      description: 'Show the close button in the corner.',
      type: 'boolean',
      default: 'false',
    },
    className: {
      description: 'Classes for the dialog content.',
      type: 'string',
    },
  }}
/>

### CommandItem [#commanditem]

<TypeTable
  type={{
    onSelect: {
      description: 'Called when the item is clicked or chosen with Enter.',
      type: '(value: string) => void',
    },
    value: {
      description:
        'A unique value used for filtering and selection. Defaults to the text content.',
      type: 'string',
    },
    keywords: {
      description: 'Extra words the item should match.',
      type: 'string[]',
    },
    disabled: {
      description: 'Keep the item visible but not selectable.',
      type: 'boolean',
      default: 'false',
    },
    forceMount: {
      description: 'Always render the item, even when it does not match.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

## API Reference [#api-reference]

[cmdk](https://github.com/pacocoursey/cmdk#parts-and-styling)

# Comparison (/docs/ui/comparison)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Comparison,
  ComparisonHandle,
  ComparisonItem,
} from '@vitnode/core/components/ui/comparison'
```

```tsx
<Comparison aria-label="Before and after" className="aspect-video">
  <ComparisonItem position="left">
    <img alt="" draggable={false} src={before} />
  </ComparisonItem>
  <ComparisonItem position="right">
    <img alt="" draggable={false} src={after} />
  </ComparisonItem>
  <ComparisonHandle />
</Comparison>
```

`position="left"` is the image left of the handle, `right` the one on its
right. Images fill their item with `object-cover`, so give `Comparison` a size
or aspect ratio.

Tap somewhere new and the handle glides there, then follows your finger one to
one. Keyboard steps glide too.

## Hover mode [#hover-mode]

With `mode="hover"` the handle follows the pointer, no click needed. Fun for
quick looks; stick with dragging for anything precise.

## Starting point and changes [#starting-point-and-changes]

```tsx
<Comparison defaultPosition={30} onPositionChange={setPosition}>
  ...
</Comparison>
```

`position` runs from 0 (all right image) to 100 (all left image).

## Custom handle [#custom-handle]

Pass children to `ComparisonHandle` to draw your own. It still moves with the
slider.

```tsx
<ComparisonHandle>
  <div className="bg-primary absolute inset-y-0 w-0.5" />
  <div className="bg-primary text-primary-foreground relative flex size-8 items-center justify-center rounded-full">
    <ChevronsLeftRightIcon className="size-4" />
  </div>
</ComparisonHandle>
```

## Accessibility [#accessibility]

- The comparison is a slider. Arrow keys move 5% (10% with <kbd>Shift</kbd>);
  <kbd>Home</kbd> and <kbd>End</kbd> jump to the ends.
- Screen readers hear the position as a percentage. Name it with `aria-label`.
- Images are decorative (`alt=""`). Describe the comparison in the label or a
  caption.
- Dragging sideways never blocks vertical page scrolling on phones.
- With reduced motion, the handle jumps instead of gliding.

## Props [#props]

# Confirm Action Alert Dialog (/docs/ui/confirm-action-alert-dialog)

An [Alert Dialog](/docs/ui/alert-dialog) with the boring parts done: async
submit, spinner, locked Cancel, and a dialog that stays open when things fail.

## Preview [#preview]

## Usage [#usage]

```tsx
import { ConfirmActionAlertDialog } from '@vitnode/core/components/confirm-action/confirm-action-alert-dialog'
import { Button } from '@vitnode/core/components/ui/button'
```

```tsx
<ConfirmActionAlertDialog
  icon={<Trash2Icon />}
  onSubmit={async ({ onClose }) => {
    await deleteCategory(id)
    onClose()
  }}
  title="Delete General discussion?"
>
  <Button variant="destructive">Delete category</Button>
</ConfirmActionAlertDialog>
```

The child becomes the trigger. Passing an `icon` switches to the compact,
centered layout.

## Async and errors [#async-and-errors]

While `onSubmit` runs, the confirm button spins and Cancel is locked. Nothing
closes until you call `onClose()`, so on an error just show a toast and return.

```tsx
onSubmit={async ({ onClose }) => {
  const result = await deleteCategoryApi(id)

if (result?.error) {
    toast.error(tGlobal('errors.title'), {
      description: tGlobal('errors.internal_server_error'),
    })

return
  }

toast.success(t('success'), { description: title })
  onClose()
}}
```

## Props [#props]

<TypeTable
  type={{
    onSubmit: {
      description: 'Runs on confirm. Call `onClose` to close the dialog.',
      type: '(params: { onClose: () => void }) => Promise<void> | void',
      required: true,
    },
    children: {
      description: 'The trigger. Leave it out when you control `open`.',
      type: 'ReactElement',
    },
    title: {
      description: 'Dialog title.',
      type: 'ReactNode',
      default: '"Are you sure?"',
    },
    description: {
      description: 'What happens on confirm.',
      type: 'ReactNode',
      default: '"This action cannot be undone."',
    },
    icon: {
      description:
        'Icon above the title. Switches to the compact, centered layout.',
      type: 'ReactNode',
    },
    textSubmit: {
      description: 'Confirm button text.',
      type: 'string',
      default: '"Yes, confirm"',
    },
    submitVariant: {
      description:
        'Confirm button variant. `destructive` also tints the icon tile red.',
      type: 'Button["variant"]',
      default: '"destructive"',
    },
    finalFocus: {
      description: 'Where focus goes after the dialog closes.',
      type: 'AlertDialogContent["finalFocus"]',
    },
  }}
/>

It also takes every `AlertDialog` prop, such as `open` and `onOpenChange`.
Default texts are translated.

# Context Menu (/docs/ui/context-menu)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  ContextMenu,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuShortcut,
  ContextMenuTrigger,
} from '@vitnode/core/components/ui/context-menu'
```

```tsx
<ContextMenu>
  <ContextMenuTrigger className="flex h-40 items-center justify-center rounded-xl border-2 border-dashed">
    Right-click here
  </ContextMenuTrigger>
  <ContextMenuContent className="w-56">
    <ContextMenuItem>
      Reload
      <ContextMenuShortcut>⌘R</ContextMenuShortcut>
    </ContextMenuItem>
    <ContextMenuItem>Rename</ContextMenuItem>
    <ContextMenuSeparator />
    <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
  </ContextMenuContent>
</ContextMenu>
```

Right-click the trigger, or long-press it on touch. The menu opens right under
your cursor or finger.

## Submenus [#submenus]

Nest a `ContextMenuSub` for the rarely used stuff. It opens on hover, click or
the right arrow.

```tsx
<ContextMenuSub>
  <ContextMenuSubTrigger>More tools</ContextMenuSubTrigger>
  <ContextMenuSubContent className="w-48">
    <ContextMenuItem>Developer tools</ContextMenuItem>
  </ContextMenuSubContent>
</ContextMenuSub>
```

## Checkbox and radio items [#checkbox-and-radio-items]

`ContextMenuCheckboxItem` toggles on its own, items in a
`ContextMenuRadioGroup` pick one. Both work controlled or uncontrolled.

```tsx
<ContextMenuCheckboxItem checked={showBookmarks} onCheckedChange={setShowBookmarks}>
  Show bookmarks bar
</ContextMenuCheckboxItem>
<ContextMenuRadioGroup onValueChange={setPerson} value={person}>
  <ContextMenuRadioItem value="pedro">Pedro Duarte</ContextMenuRadioItem>
</ContextMenuRadioGroup>
```

The check mark sits at the start of the row, like in the
[Dropdown Menu](/docs/ui/dropdown-menu). Add `inset` to plain items, labels and
sub-triggers in the same menu so their text lines up.

## Shortcuts and destructive items [#shortcuts-and-destructive-items]

`ContextMenuShortcut` is only a label: bind the keys yourself. Use
`variant="destructive"` for actions you can't take back.

```tsx
<ContextMenuItem variant="destructive">
  <Trash2Icon />
  Delete
  <ContextMenuShortcut>⌘⌫</ContextMenuShortcut>
</ContextMenuItem>
```

## Always offer another way [#always-offer-another-way]

Nothing on screen says "right-click me", and keyboard users can't open a
context menu at all. Put every action somewhere visible too, like the `⋯`
[Dropdown Menu](/docs/ui/dropdown-menu) on each row above.

## Accessibility [#accessibility]

- Once open, arrow keys move between items, right opens a submenu, a letter
  jumps to a match and <kbd>Escape</kbd> closes it.
- The trigger sets `select-none`, so a long-press doesn't start a text
  selection. Rows grow to a 44px tap target on touch screens.
- Reduced motion turns the scale-in off.

## Props [#props]

### ContextMenu [#contextmenu]

<TypeTable
  type={{
    open: {
      description: 'Controls whether the menu is open.',
      type: 'boolean',
    },
    defaultOpen: {
      description: 'Open on the first render.',
      type: 'boolean',
      default: 'false',
    },
    onOpenChange: {
      description: 'Called when the menu opens or closes.',
      type: '(open: boolean, eventDetails) => void',
    },
    disabled: {
      description: 'Stops the menu from opening.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

### ContextMenuContent [#contextmenucontent]

### ContextMenuItem [#contextmenuitem]

`ContextMenuCheckboxItem` takes `checked`, `defaultChecked` and
`onCheckedChange`; `ContextMenuRadioGroup` takes `value`, `defaultValue` and
`onValueChange`. Both item types accept `inset` and `disabled` too.

## API Reference [#api-reference]

[Base UI - Context Menu](https://base-ui.com/react/components/context-menu#api-reference)

# Copy Button (/docs/ui/copy-button)

## Preview [#preview]

## Usage [#usage]

```ts
import { CopyButton } from '@vitnode/core/components/ui/copy-button'
```

```tsx
<CopyButton content="pnpm create vitnode-app@canary" />
```

The check stays for `delay` (2000ms). Each new copy restarts the timer.

## With a label [#with-a-label]

Children show next to the icon and become the accessible name.

```tsx
<CopyButton content={inviteLink} variant="secondary">
  Copy invite link
</CopyButton>
```

## Icon only [#icon-only]

Without children it's labelled "Copy" / "Copied". With several on a screen,
give each its own `aria-label`.

```tsx
<CopyButton
  aria-label="Copy install command"
  content={command}
  size="icon-sm"
  variant="ghost"
/>
```

## Controlled [#controlled]

Use `copied` and `onCopiedChange` when the page should react.

```tsx
const [copied, setCopied] = React.useState(false)

<CopyButton content={inviteLink} copied={copied} onCopiedChange={setCopied} />
```

## Async content [#async-content]

Text that has to be fetched first? Pass a function instead of a string. It runs
on click, the button is `aria-busy` while it waits, and extra clicks are ignored
until it settles.

```tsx
<CopyButton
  content={async () => {
    const res = await fetch('/docs/dev.md')
    if (!res.ok) throw new Error(`Failed to load ${res.url}`)

return await res.text()
  }}
  size="sm"
  variant="secondary"
>
  Copy Markdown
</CopyButton>
```

Safari only lets a page write to the clipboard during the click itself, so the
pending text goes in as a `ClipboardItem` promise. Browsers without
`ClipboardItem` wait for the text, then copy it. A rejected promise shows the
same error toast as a blocked clipboard.

## Accessibility [#accessibility]

- A polite live region announces "Copied".
- With reduced motion, icons just fade and the check appears fully drawn.
- A blocked clipboard (say, on plain HTTP) shows an error toast.
- `event.preventDefault()` in your own `onClick` skips the copy.

## Props [#props]

<TypeTable
  type={{
    content: {
      description:
        'Text written to the clipboard, or an async function that resolves it on click.',
      type: 'string | (() => Promise<string>)',
      required: true,
    },
    copied: { description: 'Controls the copied state.', type: 'boolean' },
    onCopiedChange: {
      description: '`true` after a copy, `false` when the button resets.',
      type: '(copied: boolean) => void',
    },
    delay: {
      description: 'How long the check stays, in ms. Restarts on each copy.',
      type: 'number',
      default: '2000',
    },
    variant: {
      description: 'Button variant.',
      type: 'default | secondary | outline | ghost | hover | link | success | warning | destructive',
      default: 'outline',
    },
    size: {
      description:
        'Button size. Default: `icon` without children, `default` with.',
      type: 'default | xs | sm | lg | icon | icon-xs | icon-sm | icon-lg',
    },
    'aria-label': {
      description: 'Accessible name. Without children: "Copy" / "Copied".',
      type: 'string',
    },
  }}
/>

## API Reference [#api-reference]

[Base UI - Button](https://base-ui.com/react/components/button#api-reference)

# Counter (/docs/ui/counter)

## Preview [#preview]

## Usage [#usage]

```ts
import { Counter } from '@vitnode/core/components/ui/counter'
```

```tsx
const [quantity, setQuantity] = React.useState(1)

<Counter aria-label="Tickets" max={10} min={1} onValueChange={setQuantity} value={quantity} />
```

Digits roll the short way round: 9 → 10 rolls to 0 as a new 1 slides in. For
uncontrolled use, pass `defaultValue`.

## Steps and limits [#steps-and-limits]

A step that would pass a limit stops at it: with `max={12}` and `step={5}`,
10 goes to 12. Buttons disable at `min` and `max`.

## Sliding number [#sliding-number]

The rolling digits on their own, for any number.

```ts
import { SlidingNumber } from '@vitnode/core/components/ui/sliding-number'
```

```tsx
<SlidingNumber className="text-5xl font-semibold" value={downloads} />
```

It inherits font size and color, uses tabular figures, and handles negatives
and up to 6 decimals.

## In a form [#in-a-form]

Counter is a standalone control. To save a number with AutoForm, use
[Number Field](/docs/ui/number-field).

## Accessibility [#accessibility]

- The buttons are labelled "Decrease" / "Increase" in the user's language.
- Screen readers hear each new value, not the rolling digits.
- Name the counter with `aria-label` or `aria-labelledby`. "Increase" what?
- With reduced motion, digits change instantly.

## Props [#props]

### Counter [#counter]

<TypeTable
  type={{
    value: { description: 'Current value (controlled).', type: 'number' },
    defaultValue: {
      description: 'Starting value when uncontrolled.',
      type: 'number',
      default: '0',
    },
    onValueChange: {
      description: 'Called with the new value after a click.',
      type: '(value: number) => void',
    },
    min: { description: 'Lowest allowed value.', type: 'number' },
    max: { description: 'Highest allowed value.', type: 'number' },
    step: {
      description: 'Amount one click adds or removes.',
      type: 'number',
      default: '1',
    },
    disabled: {
      description: 'Disables both buttons.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

### SlidingNumber [#slidingnumber]

# Bulk Actions (/docs/ui/data-table/bulk-actions)

## Preview [#preview]

## Usage [#usage]

Passing `bulkActions` turns selection on. Each row gets a checkbox, and the
header checkbox ticks the whole page. While anything is ticked, a bar floats at
the bottom of the viewport with the count, your actions and a clear button.

```tsx
<ContentDataTable
  id="users-table"
  // [!code ++]
  bulkActions={<DeleteBulkAction />}
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```

Actions render inside the bar, so they read the ticked ids with
`useDataTableSelection()`. No props to thread through.

```tsx title="delete-bulk-action.tsx"
import { useDataTableSelection } from '@vitnode/core/components/table/selection'
import { Button } from '@vitnode/core/components/ui/button'

export const DeleteBulkAction = () => {
  const { clear, selected } = useDataTableSelection()

return (
    <Button
      onClick={async () => {
        await deleteUsers(selected)
        clear()
      }}
      variant="destructive"
    >
      <Trash2Icon />
      Delete
    </Button>
  )
}
```

## Selection is per page [#selection-is-per-page]

Selection only covers the rows on screen. When paging, search or a filter
brings different rows, ticks on rows that left are dropped. A bulk action never
touches a row nobody can see.

After a partial success, revalidate. Rows that were refused stay on screen and
stay ticked, so the bar points at the work that's left.

<Callout type="warn" title="There is no bulk endpoint">
  `bulkActions` hands you ids, nothing more. If your action loops a single-row
  endpoint, cap the fan-out and report outcomes per reason, so a partial success
  can say so.
</Callout>

## useDataTableSelection [#usedatatableselection]

<TypeTable
  type={{
    selected: {
      description: 'Ticked row ids, in the order they were ticked.',
      type: 'number[]',
    },
    isSelected: {
      description: 'Whether one row is ticked.',
      type: '(id: number) => boolean',
    },
    allSelected: {
      description: 'Every row on the page is ticked.',
      type: 'boolean',
    },
    someSelected: {
      description: 'Some but not all rows are ticked.',
      type: 'boolean',
    },
    toggle: {
      description: 'Ticks or unticks one row.',
      type: '(id: number) => void',
    },
    toggleAll: {
      description: 'Ticks or unticks every row on the page.',
      type: '(next: boolean) => void',
    },
    clear: {
      description: 'Unticks everything and hides the bar.',
      type: '() => void',
    },
  }}
/>

The hook throws outside a table with `bulkActions`.

# Custom Rows (/docs/ui/data-table/custom-rows)

## Preview [#preview]

## Usage [#usage]

Columns suit data you compare across rows. When each row is more of a card
(an icon, a title, a line of description and a switch), pass `renderRow`
instead of `columns`. The Data Table draws your layout across the full width
of the row and still handles search, filters, pagination and the empty state.

```tsx
<ContentDataTable
  id="plugins-table"
  // [!code ++:3]
  renderRow={({ row }) => (
    <PluginRow plugin={row} />
  )}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```

- **No column headers.** A custom row has no columns to label, so the header
  band is hidden. It comes back when you turn on `bulkActions`, `expandable` or
  `reorderable`, because their controls live there.
- **Row features still work.** The checkbox, the expand chevron and the drag
  handle sit in front of your layout, and `rowOpens` makes the whole row
  clickable.
- **Controls answer for themselves.** A click on a button, link or switch
  inside your layout does not trigger `rowOpens`.
- **Your layout owns its spacing.** The cell already has the row's padding, so
  don't add outer padding of your own.

<Callout type="info" title="Sorting needs a column header">
  `order.defaultOrder` still sets the starting order, but there are no headers
  to click. To let people change the order, add a filter or sort the rows
  yourself.
</Callout>

## API [#api]

<TypeTable
  type={{
    renderRow: {
      description:
        'Renders one row. `allData` holds every row on the current page. Takes over from `columns`.',
      type: '(data: { row: T; allData: T[] }) => ReactNode',
    },
  }}
/>

Want those rows sorted into categories? Combine `renderRow` with
[grouped rows](/docs/ui/data-table/grouped-rows).

# Draggable Rows (/docs/ui/data-table/draggable-rows)

## Preview [#preview]

## Usage [#usage]

When the order _is_ the data, like a backlog or an FAQ, pass `reorderable`. Each
row gets a grip handle.

```tsx
<ContentDataTable
  id="backlog-table"
  // [!code ++:4]
  reorderable={{
    getRowLabel: (task) => task.title,
    onReorder: async (ids) => await saveOrder(ids),
  }}
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'position', order: 'asc' } }}
/>
```

- **Optimistic.** The row moves on drop and `onReorder` runs in the background.
  If it rejects, the rows jump back and an error toast appears.
- **Only the handle drags.** Links, buttons and `rowOpens` in the row keep
  working.
- **Mouse, touch and keyboard.** On touch, press and hold the handle briefly so
  the page still scrolls. With a keyboard, focus a handle, press Space, move
  with the arrows, Space to drop, Escape to cancel. Screen readers hear every
  move.
- **Plays with the rest.** Open detail panels travel with their row. With
  `bulkActions`, the handle sits before the checkbox. Reduced motion swaps rows
  without sliding.

<Callout type="warn" title="Reordering pauses in a filtered view">
  Handles lock while a search, filter or non-default sort is active, because
  dragging there would shuffle rows nobody can see. Hovering says why. Make
  `defaultOrder` your stored order, like `position` ascending.
</Callout>

## API [#api]

<TypeTable
  type={{
    onReorder: {
      description:
        'Called after a drop with every row id on the page in its new order. Reject to roll back.',
      required: true,
      type: `(ids: number[], details: {
        activeId: number;
        overId: number;
        from: number;
        to: number;
      }) => void | Promise<void>`,
    },
    getRowLabel: {
      description:
        'The handle\'s accessible name, like "Reorder Fix the login loop". Defaults to the row position.',
      type: '(row: T) => string',
    },
    disabled: {
      description: 'Shows the handles but locks them, e.g. without permission.',
      type: 'boolean',
    },
  }}
/>

## Save the order [#save-the-order]

The table hands you ids. Three pieces make them stick. VitNode's navigation
admin does the same in
`packages/vitnode/src/api/modules/admin/navigation/routes/reorder.route.ts`.

#### Add a `position` column [#add-a-position-column]

```ts title="plugins/tasks/src/database/tasks.ts"
export const tasks = camelCase.table.withRLS(
  'tasks',
  (t) => ({
    id: t.serial().primaryKey(),
    title: t.varchar({ length: 255 }).notNull(),
    // [!code ++]
    position: t.integer().notNull().default(0),
  }),
  // [!code ++]
  (t) => [index('tasks_position_idx').on(t.position)],
)
```

Sort the list route by it with `orderBy: { column: tasks.position, order: 'asc' }`.
Give new rows the current maximum plus one, or ties sort at random.

</Step>
<Step>

#### Accept the order in an admin route [#accept-the-order-in-an-admin-route]

The route gets one page of ids and hands those rows the positions they already
held between them, so reordering page 3 never touches page 1. Admin routes
always need a staff permission.

```ts title="plugins/tasks/src/api/modules/admin/tasks/routes/reorder.route.ts"
export const reorderTasksRoute = buildRoute({
  pluginId: CONFIG_PLUGIN.pluginId,
  // [!code ++]
  adminStaffPermission: { module: 'tasks', permission: 'can_reorder' },
  route: {
    method: 'post',
    path: '/reorder',
    description: 'Save the order of one page of tasks (Admin only)',
    request: {
      body: {
        required: true,
        content: {
          'application/json': {
            schema: z.object({
              ids: z.array(z.number().int()).min(1).max(100),
            }),
          },
        },
      },
    },
    responses: {
      200: { description: 'Tasks reordered' },
      400: {
        content: {
          'application/json': { schema: z.object({ error: z.string() }) },
        },
        description: 'Duplicated or unknown ids',
      },
      403: { description: 'Access Denied' },
    },
  },
  handler: async (c) => {
    const { ids } = c.req.valid('json')
    const db = c.get('db')

if (new Set(ids).size !== ids.length) {
      return c.json({ error: 'A task appears twice in the new order' }, 400)
    }

const current = await db
      .select({ position: tasks.position })
      .from(tasks)
      .where(inArray(tasks.id, ids))

if (current.length !== ids.length) {
      return c.json({ error: 'The new order names an unknown task' }, 400)
    }

const slots = current.map((row) => row.position).sort((a, b) => a - b)

await db.transaction(async (tx) => {
      for (const [index, id] of ids.entries()) {
        await tx
          .update(tasks)
          .set({ position: slots[index] })
          .where(eq(tasks.id, id))
      }
    })

return c.body(null, 200)
  },
})
```

Declare the permission in the plugin's API config:

```ts title="plugins/tasks/src/config.api.ts"
permissionStaff: {
  admin: {
    tasks: ['can_view', { permission: 'can_reorder', dependsOn: ['can_view'] }],
  },
},
```

</Step>
<Step>

#### Call it from `onReorder` [#call-it-from-onreorder]

Throw to roll back. On success, invalidate the list so other views catch up.

```tsx
reorderable={{
  getRowLabel: task => task.title,
  onReorder: async ids => {
    const res = await fetcher({
      plugin: '@acme/tasks',
      method: 'post',
      module: 'admin/tasks',
      path: '/reorder',
      args: { body: { ids } },
    })

if (!res.ok) throw new Error('Saving the order failed')

await queryClient.invalidateQueries({ queryKey: tasksQueryKey })
  },
}}
```

</Step>
</Steps>

# Expandable Rows (/docs/ui/data-table/expandable-rows)

## Preview [#preview]

## Usage [#usage]

For rows with more to say than a cell holds, like an order's line items or a
job's error log. Each row gets a chevron that opens a panel in place.

```tsx
<ContentDataTable
  id="orders-table"
  // [!code ++:4]
  expandable={{
    render: (order) => <OrderDetail order={order} />,
    canExpand: (order) => order.items.length > 0,
  }}
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'number', order: 'asc' } }}
/>
```

- **Several rows can be open.** Open state lives in the component, not the URL,
  and rows that leave the page are forgotten.
- **The chevron is a real button** with `aria-expanded` and `aria-controls`.
  Enter and Space work, and `rowOpens` clicks still work on the rest of the row.
- **Works with `bulkActions`.** The chevron sits right after the checkbox.
- **Polite motion.** The panel springs open in about 300ms. With reduced motion
  it only fades.

<Callout type="info" title="Fetch heavy details in the panel">
  `render` runs only while a row is open. If the panel needs data the list
  didn't load, fetch it inside the panel with TanStack Query, so re-opening is
  instant.
</Callout>

## API [#api]

<TypeTable
  type={{
    render: {
      description: 'Renders the detail panel for an open row.',
      required: true,
      type: '(row: T) => ReactNode',
    },
    canExpand: {
      description:
        "Return false to hide a row's chevron. All rows expand by default.",
      type: '(row: T) => boolean',
    },
    defaultExpanded: {
      description: 'Row ids open on the first render.',
      type: 'number[]',
    },
  }}
/>

# Filters (/docs/ui/data-table/filters)

## Preview [#preview]

## Usage [#usage]

Each filter is a multi-select dropdown next to the search input. It owns one
query parameter and stores picks comma-separated, like `?roleId=1,3`. Changing a
filter returns to page one.

```tsx
<ContentDataTable
  id="users-table"
  // [!code ++:9]
  filters={[
    {
      id: 'status',
      label: 'Status',
      options: [
        { value: 'active', label: 'Active' },
        { value: 'banned', label: 'Banned' },
      ],
    },
  ]}
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```

Static `options` are searched on the client.

## Async options [#async-options]

For long lists, pass `onSearch` instead. It runs when the dropdown opens and
400ms after typing stops. Return results already filtered and capped by the
server.

```tsx title="search-roles.tsx"
import type { FilterOption } from '@vitnode/core/components/table/filters'

import { RoleFormatContent } from '@vitnode/core/components/role-format-content'
import { fetcher } from '@vitnode/core/tanstack/fetcher'

export const searchRoles = async (search: string): Promise<FilterOption[]> => {
  const res = await fetcher({
    plugin: '@vitnode/core',
    method: 'get',
    module: 'admin/roles',
    path: '/list',
    args: { query: { search, first: '20' } },
    withPagination: true,
  })

if (res.status !== 200) return []

const data = await res.json()

return data.edges.map((role) => ({
    value: String(role.id),
    label: <RoleFormatContent role={role} />,
    keywords: role.name.map((item) => item.name),
  }))
}
```

```tsx
filters={[{ id: 'roleId', label: 'Group', onSearch: searchRoles }]}
```

## Read it in the API [#read-it-in-the-api]

A filter only writes to the URL. The API route reads the parameter and adds the
`where` clause:

```ts
const roleIds = (query.roleId?.split(',') ?? [])
  .filter(Boolean)
  .map(Number)
  .filter(id => !Number.isNaN(id))

where: roleIds.length ? inArray(core_users.roleId, roleIds) : undefined,
```

## API [#api]

<TypeTable
  type={{
    id: {
      description: 'The query parameter this filter reads and writes.',
      required: true,
      type: 'string',
    },
    label: {
      description: 'Trigger text and search placeholder.',
      required: true,
      type: 'string',
    },
    options: {
      description:
        'Static options. Add `keywords` so a node `label` is searchable.',
      type: `{ value: string; label: ReactNode; keywords?: string[] }[]`,
    },
    onSearch: {
      description: 'Async source, called on open and as the user types.',
      type: '(search: string) => Promise<FilterOption[]>',
    },
  }}
/>

# Grouped Rows (/docs/ui/data-table/grouped-rows)

## Preview [#preview]

## Usage [#usage]

When rows belong to a category, like plugins by type or tasks by project, pass
`groupBy`. Return the category's name from `key`, and the Data Table puts each
category's rows under a heading that shows its name and how many rows it holds.

```tsx
<ContentDataTable
  id="plugins-table"
  // [!code ++]
  groupBy={{ key: (plugin) => plugin.category }}
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```

`groupBy` works with `columns` and with [custom rows](/docs/ui/data-table/custom-rows).
The AdminCP's **AI → Actions** page uses both: one card per action, grouped by
the plugin that registers it.

### Change the heading [#change-the-heading]

The heading shows the `key` by default. Pass `label` to render something
else, such as a translated name or an icon. The row count stays next to it.

```tsx
groupBy={{
  key: (action) => action.pluginId,
  label: (group) => <span className="font-mono">{group.key}</span>,
}}
```

### How the groups are ordered [#how-the-groups-are-ordered]

Groups appear in the order their first row does, and rows keep their order
within a group. To get groups in a particular order, sort the rows by the
category first, then by anything else. Ordering by category on the API is
usually enough.

Grouping happens per page. If a category runs across two pages, its heading
appears on both, with the count for that page.

<Callout type="warn" title="Not with draggable rows">
  When `reorderable` is set, the Data Table ignores `groupBy`. Dragging a row
  across a heading would move it into another category, and only your data can
  say whether that is allowed.
</Callout>

## API [#api]

<TypeTable
  type={{
    key: {
      description: 'Returns the group a row belongs to.',
      required: true,
      type: '(row: T) => string',
    },
    label: {
      description: 'Renders the group heading. Defaults to the key.',
      type: '(group: { key: string; rows: T[] }) => ReactNode',
    },
  }}
/>

# Data Table (/docs/ui/data-table)

## Preview [#preview]

## Usage [#usage]

```ts
import type { ColumnDef } from '@vitnode/core/components/table/data-table-content'

import { ContentDataTable } from '@vitnode/core/components/table/content'
```

```tsx
const columns: ColumnDef<User>[] = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'status', header: 'Status', align: 'center' },
  {
    id: 'actions',
    header: '',
    align: 'right',
    cell: ({ row }) => <EditUserButton id={row.id} />,
  },
]

<ContentDataTable
  id="users-table"
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```

Every row needs a numeric `id`. Render the table inside a
`DataTableNavigationProvider`, or its controls throw.

## Connect it to the URL [#connect-it-to-the-url]

The table never talks to the router. Search, filters, sorting and the pager all
hand a new query string to `navigate`, and the table renders whatever
`searchParams` says.

```tsx
import type { DataTableNavigation } from '@vitnode/core/components/table/navigation'

import { DataTableNavigationProvider } from '@vitnode/core/components/table/navigation'

const navigation = React.useMemo<DataTableNavigation>(
  () => ({
    searchParams: new URLSearchParams(search),
    navigate: async nextSearch => {
      await navigate({
        resetScroll: false,
        search: Object.fromEntries(new URLSearchParams(nextSearch)),
      })
    },
  }),
  [navigate, search],
)

<DataTableNavigationProvider value={navigation}>
  <ContentDataTable {...props} />
</DataTableNavigationProvider>
```

The route's loader then fetches the page those params describe:

```ts
const res = await fetcher({
  plugin: '@vitnode/core',
  method: 'get',
  module: 'admin/users',
  path: '/list',
  args: { query: search },
  withPagination: true,
})
```

## Columns [#columns]

An **accessor column** binds to a field with `accessorKey`, which only accepts
`keyof T`, so typos fail at compile time. A **display column** (actions,
badges) has no field and needs a string `id`.

`cell` replaces the default text and gets `{ row, allData }`. `align` sets
`'left'` (default), `'center'` or `'right'` for the header and cells. Right
suits numbers and actions.

## Sorting [#sorting]

List sortable columns in `order.columns`. Clicking a header flips between
ascending and descending and writes `?orderBy=&order=` to the URL.
`defaultOrder` applies when the URL says nothing.

```tsx
order={{
  columns: ['name', 'createdAt'],
  defaultOrder: { column: 'createdAt', order: 'desc' },
}}
```

## Clickable rows [#clickable-rows]

`rowOpens` makes the whole row a target. It's focusable, and Enter or Space
opens it too. Clicks on links, buttons and inputs inside the row are ignored.

```tsx
rowOpens={user => navigate({ to: `/admin/core/users/${user.id}` })}
```

## Features [#features]

## API [#api]

<TypeTable
  type={{
    id: {
      description: 'DOM id of the table.',
      required: true,
      type: 'string',
    },
    columns: {
      description:
        'Accessor columns (`accessorKey: keyof T`) or display columns (`id: string`). Leave out when you pass `renderRow`.',
      type: `ColumnDef<T>[]`,
    },
    renderRow: {
      description:
        'Renders each row as one full-width layout instead of column cells. Takes over from `columns`.',
      type: '(data: { row: T; allData: T[] }) => ReactNode',
    },
    groupBy: {
      description: 'Puts rows under a heading for each group.',
      type: 'GroupByDataTable<T>',
    },
    edges: {
      description: 'The rows of the current page.',
      required: true,
      type: 'T[]',
    },
    pageInfo: {
      description: 'Pagination info from the API, passed straight through.',
      required: true,
      type: `{
        count: number;
        totalCount: number;
        totalPages: number;
        pageSize: number;
        currentPage: number | null;
        hasNextPage: boolean;
        hasPreviousPage: boolean;
        startCursor: string | null;
        endCursor: string | null;
      }`,
    },
    order: {
      description: 'Sortable columns and the default sort.',
      required: true,
      type: `{
        columns?: (keyof T)[];
        defaultOrder: { column: keyof T; order: 'asc' | 'desc' };
      }`,
    },
    rowOpens: {
      description: 'Makes each row clickable and keyboard-focusable.',
      type: '(row: T) => void',
    },
    header: {
      description: 'A band above the toolbar, for a title or actions.',
      type: 'ReactNode',
    },
    customNoResults: {
      description: 'Replaces the empty state.',
      type: `{
        title?: string;
        description?: string;
        icon?: ReactNode;
        footer?: ReactNode;
      }`,
    },
    search: {
      description: 'Shows a search input.',
      type: 'boolean',
    },
    searchPlaceholder: {
      description: 'Placeholder for the search input.',
      type: 'string',
    },
    filters: {
      description: 'Faceted filters.',
      type: 'FilterDataTable[]',
    },
    bulkActions: {
      description: 'Turns on row selection.',
      type: 'ReactNode',
    },
    expandable: {
      description: 'Turns on detail panels.',
      type: 'ExpandableDataTable<T>',
    },
    reorderable: {
      description: 'Turns on drag-and-drop ordering.',
      type: 'ReorderableDataTable<T>',
    },
  }}
/>

Other props go to the underlying `Table`.

# Pagination (/docs/ui/data-table/pagination)

## Preview [#preview]

## Usage [#usage]

There's nothing to wire up. Pass `pageInfo` from the API and the table renders
numbered pages, a rows-per-page select (10, 20, 30 or 40) and a "Showing 21–30
of 380" range.

- **Pages are real links.** `?page=3` works with middle-click and "open in new
  tab", while a plain click stays client-side.
- **Phones get a label.** Below `sm`, the numbers collapse to "Page 3 of 38"
  between the arrows.
- **Filters and page size reset to page one.** The old page no longer means
  what it did.
- **Too far lands on the last page.** The API clamps a page past the end, so
  stale links still show rows.

The API does the counting. See [Pagination](/docs/dev/database/pagination) for
the route side, including the index your sorted column needs.

# Search (/docs/ui/data-table/search)

## Preview [#preview]

## Usage [#usage]

```tsx
<ContentDataTable
  id="users-table"
  // [!code ++:2]
  search
  searchPlaceholder="Search users..."
  columns={columns}
  edges={data.edges}
  pageInfo={data.pageInfo}
  order={{ defaultOrder: { column: 'name', order: 'asc' } }}
/>
```

The input writes `?search=` to the URL 500ms after typing stops. Terms shorter
than 3 characters clear it. Your route then loads the matching rows.

<Callout type="info" title="Configure the API route">
  `search` only renders the input. The API route decides which columns are
  searched. See the [Search](/docs/dev/database/search) guide.
</Callout>

# Date Picker (/docs/ui/date-picker)

The Date Picker is a [Calendar](/docs/ui/calendar) tucked inside a popover. It takes little space until someone needs it, then closes as soon as they pick a day.

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormDatePicker } from '@vitnode/core/components/form/fields/date-picker'
```

```tsx
const formSchema = z.object({
  birthday: z.iso.date('Pick your birthday'),
  anniversary: z.iso.date().optional(),
})

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'birthday',
      component: props => (
        <AutoFormDatePicker {...props} label="Birthday" />
      ),
    },
    {
      id: 'anniversary',
      component: props => (
        <AutoFormDatePicker {...props} label="Community anniversary" />
      ),
    },
  ]}
/>
```

The value is a `YYYY-MM-DD` string, so use `z.iso.date()` in the schema. It is the user's local day, with no time zone surprises on the way to your API. Optional fields get a **Clear** button.

</Tab>

```ts
import { DatePicker } from '@vitnode/core/components/ui/date-picker'
```

```tsx
const [date, setDate] = React.useState<Date>()

<Label htmlFor="event-date">Event date</Label>
<DatePicker allowClear id="event-date" onChange={setDate} value={date} />
```

</Tab>
</Tabs>

<Callout type="warn">
  `z.date()` does not work in AutoForm: the schema is turned into JSON Schema,
  which has no date type. Use `z.iso.date()` and convert on the server if you
  need a `Date`.
</Callout>

## Calendar options [#calendar-options]

`calendarProps` passes any [Calendar](/docs/ui/calendar) prop through, except the selection ones. A birthday field with year dropdowns and no future dates:

```tsx
<AutoFormDatePicker
  {...props}
  calendarProps={{
    captionLayout: 'dropdown',
    disabled: { after: new Date() },
    endMonth: new Date(),
    startMonth: new Date(1926, 0),
  }}
  label="Birthday"
/>
```

## Date format [#date-format]

The button shows the date in the active VitNode language, `October 7, 2026` in English. Pass `Intl.DateTimeFormat` options to change it.

```tsx
<DatePicker
  dateFormat={{ dateStyle: 'short' }}
  onChange={setDate}
  value={date}
/>
```

## Date range [#date-range]

`DateRangePicker` picks a start and an end day. Quick ranges on the left apply in one click; a range picked on the calendar waits for **Apply range**, so a half-finished pick never fires a request. The button shows the preset's name, or the dates like `Oct 7 – 12, 2026`.

```ts
import { DateRangePicker } from '@vitnode/core/components/ui/date-range-picker'
```

```tsx
const [range, setRange] = React.useState({ from: weekAgo, to: today })
const [preset, setPreset] = React.useState<'7d' | '30d' | null>('7d')

<DateRangePicker
  activePreset={preset}
  disabledDays={{ after: today }}
  endMonth={today}
  onChange={next => {
    setPreset(null)
    setRange(next)
  }}
  onPresetSelect={next => {
    setPreset(next)
    setRange(resolve(next))
  }}
  presets={[
    { key: '7d', label: 'Last 7 days' },
    { key: '30d', label: 'Last 30 days' },
  ]}
  value={range}
/>
```

You own the presets: `onPresetSelect` hands you the key and you work out the dates, so "Last 7 days" can mean the site's time zone instead of the browser's. The calendar shows two months on wide screens and one on phones.

## Accessibility [#accessibility]

- `AutoFormDatePicker` wires the label, description and error to the button.
- With `DatePicker` alone, give it an `id` and a `<Label htmlFor>`.
- Opening the popover moves focus into the calendar. Escape closes it and focus returns to the button.
- A validation message waits until focus leaves the field, not when the popover opens.

## Props [#props]

### DatePicker [#datepicker]

`DatePicker` also takes every `<button>` prop.

<TypeTable
  type={{
    value: { description: 'The selected date.', type: 'Date' },
    onChange: {
      description: 'Called with the picked date, or `undefined` when cleared.',
      type: '(date: Date | undefined) => void',
    },
    placeholder: {
      description: 'Text shown before a date is picked.',
      type: 'string',
      default: "'Pick a date'",
    },
    allowClear: {
      description: 'Show a Clear button in the popover.',
      type: 'boolean',
      default: 'false (AutoForm: true for optional fields)',
    },
    dateFormat: {
      description: 'How the button formats the date.',
      type: 'Intl.DateTimeFormatOptions',
      default: "{ dateStyle: 'long' }",
    },
    calendarProps: {
      description: 'Props for the inner Calendar, minus the selection ones.',
      type: 'CalendarProps',
    },
  }}
/>

`AutoFormDatePicker` takes the same props, except its `onChange` receives the `YYYY-MM-DD` string.

### DateRangePicker [#daterangepicker]

`DateRangePicker` also takes every `<button>` prop.

<TypeTable
  type={{
    value: {
      description: 'The selected range.',
      type: '{ from: Date; to: Date }',
    },
    onChange: {
      description:
        'Called with a range picked on the calendar, after Apply range.',
      type: '(range: { from: Date; to: Date }) => void',
    },
    presets: {
      description: 'Quick ranges listed beside the calendar.',
      type: '{ key: string; label: string }[]',
      default: '[]',
    },
    activePreset: {
      description:
        'The preset the current range came from. The button shows its label.',
      type: 'string | null',
    },
    onPresetSelect: {
      description:
        'Called with the key of a clicked preset. The popover closes.',
      type: '(key: string) => void',
    },
    disabledDays: {
      description: 'Days that cannot be picked, as Calendar matchers.',
      type: 'Matcher | Matcher[]',
    },
    startMonth: {
      description: 'The first month the calendar can show.',
      type: 'Date',
    },
    endMonth: {
      description: 'The last month the calendar can show.',
      type: 'Date',
    },
    align: {
      description: 'Where the popover lines up with the button.',
      type: "'start' | 'center' | 'end'",
      default: "'end'",
    },
  }}
/>

# Dialog (/docs/ui/dialog)

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@vitnode/core/components/ui/dialog'
```

```tsx
<Dialog>
  <DialogTrigger render={<Button variant="outline">Share</Button>} />
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Share this page</DialogTitle>
      <DialogDescription>Anyone with the link can read it.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose render={<Button>Done</Button>} />
    </DialogFooter>
  </DialogContent>
</Dialog>
```

Always add a `DialogTitle`. It names the dialog for screen readers.

## Forms [#forms]

Put an `AutoForm` inside and it renders a Cancel + Submit footer for you. Edit a
field, then press <kbd>Escape</kbd>: the dialog asks before throwing your
changes away.

```tsx
const EditCategoryForm = () => {
  const { setOpen } = useDialog()

return (
    <AutoForm
      fields={fields}
      formSchema={formSchema}
      onSubmit={async (values) => {
        await save(values)
        setOpen?.(false)
      }}
    />
  )
}
```

`useDialog()` gives children `setOpen` and `setIsDirty`. Closing with `setOpen`
skips the guard, so call it after a successful save. Lazy-load heavy forms
with `React.lazy` and `Suspense`.

## Long content [#long-content]

Content taller than the screen scrolls inside the dialog. The page behind stays
put.

## Nested dialogs [#nested-dialogs]

Open an [Alert Dialog](/docs/ui/alert-dialog) from inside a dialog to confirm a
risky step. Closing it brings you back to the first dialog.

## Controlled [#controlled]

```tsx
<Dialog onOpenChange={setOpen} open={open}>
  ...
</Dialog>
```

`onOpenChange` receives just the new `boolean`. Clicking a toast never closes
the dialog underneath.

## Dialog or Alert Dialog? [#dialog-or-alert-dialog]

Dialog is for low-stakes tasks and closes on an outside click. Confirming
something nobody can undo? Use an [Alert Dialog](/docs/ui/alert-dialog).

## Props [#props]

## API Reference [#api-reference]

[Base UI - Dialog](https://base-ui.com/react/components/dialog#api-reference)

# Drawer (/docs/ui/drawer)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from '@vitnode/core/components/ui/drawer'
```

```tsx
<Drawer>
  <DrawerTrigger asChild>
    <Button variant="outline">Report post</Button>
  </DrawerTrigger>
  <DrawerContent>
    <DrawerHeader>
      <DrawerTitle>What's wrong with this post?</DrawerTitle>
      <DrawerDescription>Moderators see your report.</DrawerDescription>
    </DrawerHeader>
    <DrawerFooter>
      <DrawerClose asChild>
        <Button variant="ghost">Cancel</Button>
      </DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>
```

`DrawerTrigger` and `DrawerClose` take `asChild` or Base UI's `render` to use
your own button. Wrap wide content in `mx-auto max-w-sm` so it doesn't stretch
across a desktop.

## Direction and swipe [#direction-and-swipe]

`direction` picks the edge: `bottom` (default), `top`, `left` or `right`. Swipe
toward that edge to close. A quick flick closes it even from a short drag, a
slow nudge springs back, and the backdrop fades as you drag.

```tsx
<Drawer direction="right">...</Drawer>
```

Bottom drawers get a grab handle and stop at 80% of the screen height. With
reduced motion on, the drawer opens and closes instantly, but dragging still
follows your finger.

## Props [#props]

## API Reference [#api-reference]

[Base UI - Drawer](https://base-ui.com/react/components/drawer)

# Dropdown Menu (/docs/ui/dropdown-menu)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
  DropdownMenuTrigger,
} from '@vitnode/core/components/ui/dropdown-menu'
```

```tsx
<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline">Open</Button>} />
  <DropdownMenuContent className="w-56">
    <DropdownMenuLabel>My Account</DropdownMenuLabel>
    <DropdownMenuItem>
      Profile
      <DropdownMenuShortcut>⇧⌘P</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem>Log out</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

The menu matches the trigger's width (at least `min-w-36`). Set a width with
`className` when the trigger is small. `DropdownMenuShortcut` is only a label:
bind the keys yourself.

Nest `DropdownMenuSub`, `DropdownMenuSubTrigger` and `DropdownMenuSubContent`
for a submenu. It opens on hover, click or the right arrow.

## Icon trigger and destructive items [#icon-trigger-and-destructive-items]

An icon-only trigger needs an `aria-label`. Use `align="end"` when the trigger
sits at the end of a row, and `variant="destructive"` for actions you can't
take back.

```tsx
<DropdownMenuTrigger
  render={
    <Button aria-label="Post actions" size="icon-sm" variant="ghost">
      <EllipsisIcon />
    </Button>
  }
/>
<DropdownMenuContent align="end">
  <DropdownMenuItem variant="destructive">
    <Trash2Icon />
    Delete
  </DropdownMenuItem>
</DropdownMenuContent>
```

## Checkbox and radio items [#checkbox-and-radio-items]

`DropdownMenuCheckboxItem` toggles on its own. Items in a
`DropdownMenuRadioGroup` pick one. The check mark sits at the start of the row,
like in the [Context Menu](/docs/ui/context-menu) and
[Menubar](/docs/ui/menubar). Add `inset` to labels and plain items in the same
menu so their text lines up.

```tsx
<DropdownMenuCheckboxItem checked={showPinned} onCheckedChange={setShowPinned}>
  Pinned threads
</DropdownMenuCheckboxItem>
<DropdownMenuRadioGroup onValueChange={setSort} value={sort}>
  <DropdownMenuRadioItem value="latest">Latest activity</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
```

## Accessibility [#accessibility]

- Arrow keys move between items, typing a letter jumps to a match and
  <kbd>Escape</kbd> closes the menu and returns focus to the trigger.
- Rows grow to a 44px tap target on touch screens. Long menus scroll without
  dragging the page.
- The menu scales in from its trigger in 150ms and leaves in 100ms. Reduced
  motion turns that off.

## Props [#props]

### DropdownMenuContent [#dropdownmenucontent]

`DropdownMenuSubContent` opens to the `right` with `alignOffset={-4}`, so its
first item lines up with the sub-trigger.

### DropdownMenuItem [#dropdownmenuitem]

`DropdownMenuLabel` and `DropdownMenuSubTrigger` accept `inset` too.

## API Reference [#api-reference]

[Base UI - Menu](https://base-ui.com/react/components/menu#api-reference)

# Editor (/docs/ui/editor)

## Preview [#preview]

Type <kbd>/</kbd> for blocks or <kbd>:</kbd> for emoji. Your fingers never leave
the keyboard, and your coffee stays safe.

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormEditor } from '@vitnode/core/components/form/fields/editor'

const formSchema = z.object({
  content: z.string().min(1, 'Write something first'),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'content',
      component: (props) => <AutoFormEditor {...props} label="Announcement" />,
    },
  ]}
/>
```

</Tab>

`value` is the initial HTML. `onChange` gets the current HTML on every edit.

```tsx
import { Editor } from '@vitnode/core/components/ui/editor'

const [content, setContent] = useState('<p>Hello World! 🌎️</p>')

;<Editor onChange={setContent} value={content} />
```

</Tab>
</Tabs>

## Toolbar [#toolbar]

One row, even in a narrow form. Everyday tools sit up front, the rest in menus:

- **Text style**: paragraph or heading 1–4.
- **Bold**, **italic** and **…**: underline, strikethrough, inline code,
  alignment, _Clear formatting_.
- **Text color**, **lists** (bulleted, numbered, task), **link**, **emoji**,
  **table**, **code block**.
- **+ Insert**: quote, code block, table, divider, emoji, audio and panels.

## Slash commands [#slash-commands]

Type <kbd>/</kbd>, keep typing to filter (`/tab` finds _Table_), pick with the
arrow keys and <kbd>Enter</kbd>. Search matches translated names and English
keywords, so `/table` works in every language.

## Emoji [#emoji]

Type <kbd>:</kbd> and a few letters (`:rocket`) to get suggestions, or use the
toolbar picker. Add your own emoji for every editor in `vitnode.config.ts`:

```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  editor: {
    emojis: [
      {
        label: 'VitNode',
        emojis: [
          { name: 'vitnode', src: '/logo.svg', tags: ['logo', 'brand'] },
        ],
      },
    ],
  },
})
```

`name` is the shortcode (`:vitnode:`), `tags` are extra search words, and
`label` heads the section in the picker.

## Panels [#panels]

Callouts in four kinds: `info`, `warning`, `error`, `success`. One paragraph is
a muted note. Add a second and the first becomes the title.

Insert one from **+ Insert** or `/panel`. Picking the same kind again removes
it; another kind switches the color. Panels are saved as plain HTML,
`<div class="tiptap-panel" data-panel="info">`, so `EditorContent` renders them
as is.

## Task lists [#task-lists]

Each item stores its checkbox state, so acceptance criteria stay ticked after
saving. Start one from the toolbar, `/task`, or type `[ ]` at the start of a
line.

## Keyboard shortcuts [#keyboard-shortcuts]

| Action          | Shortcut                                                                      |
| --------------- | ----------------------------------------------------------------------------- |
| Submit the form | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Enter</kbd>                               |
| Bold / italic   | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>B</kbd> / <kbd>I</kbd>                    |
| Underline       | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>U</kbd>                                   |
| Bulleted list   | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>8</kbd>                |
| Numbered list   | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>7</kbd>                |
| Task list       | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Shift</kbd> + <kbd>9</kbd>                |
| Undo / redo     | <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Z</kbd> / <kbd>Shift</kbd> + <kbd>Z</kbd> |

<kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>Enter</kbd> submits the surrounding form,
like its submit button. Outside a form it does nothing.

## Accessibility [#accessibility]

- The toolbar is one tab stop. <kbd>←</kbd> <kbd>→</kbd> move between buttons,
  <kbd>Home</kbd> / <kbd>End</kbd> jump to the ends.
- In AutoForm, the writing area is named by the label, described by the
  description and error, and outlined red when invalid.
- The `/` and `:` menus announce the highlighted option, and open upward when
  there's no room below.
- A same-size placeholder holds the spot while the editor loads, so the page
  doesn't jump.

## Multi-language [#multi-language]

Add `multiLang` to edit the content in every enabled language. A language select
(shown with two or more languages) switches the language being edited, not the
app locale.

```ts
import { multiLangValueSchema } from '@vitnode/core/lib/helpers/multi-lang'

const formSchema = z.object({
  content: multiLangValueSchema({ minLength: 1 }).min(1),
})
```

```tsx
<AutoFormEditor {...props} label="Content" multiLang />
```

The value becomes `{ languageCode, value }[]`, matching `core_languages_words`:

```ts
const value = [
  { languageCode: 'en', value: '<p>Hello</p>' },
  { languageCode: 'pl', value: '<p>Cześć</p>' },
]
```

Save it with `saveLanguageWords`. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields).

## Rendering content [#rendering-content]

`EditorContent` renders stored HTML read-only, for public pages. It sanitizes
the HTML first, so a sneaky `<script>` never runs.

```tsx
import { EditorContent } from '@vitnode/core/components/ui/editor-content'

;<EditorContent content={post.content} />
```

## Props [#props]

<TypeTable
  type={{
    value: {
      description: 'Initial HTML content.',
      type: 'string',
      default: '""',
    },
    onChange: {
      description: 'Called on every change with the current HTML.',
      type: '(value: string) => void',
    },
    placeholder: {
      description: 'Shown while the editor is empty.',
      type: 'string',
      default: '"Write something…"',
    },
    disableScroll: {
      description:
        'Removes the max-height scroll area so the editor grows with its content.',
      type: 'boolean',
      default: 'false',
    },
    className: {
      description: 'Extra classes for the editor wrapper.',
      type: 'string',
    },
    multiLang: {
      description:
        'AutoFormEditor only. Edit per language; the value becomes { languageCode, value }[].',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

# Radius & Elevation (/docs/ui/elevation)

One variable sets every corner, six soft shadows set every height, and in dark
mode the surfaces themselves get lighter as they rise. Depth without the drama.

## Radius scale [#radius-scale]

Every `rounded-*` class is a multiple of `--radius` (`0.75rem`). Drag the slider
to feel it: change the one variable in `src/styles.css` and the whole UI gets
rounder or sharper.

```css
:root {
  --radius: 0.75rem;
}
```

## Corners nest [#corners-nest]

Inner radius = outer radius − padding. Copy the outer radius onto the inner box
and the corners bulge like a badly packed suitcase. That's why menus are
`rounded-lg` with `p-1` and their items are `rounded-sm`.

```tsx
<div className="rounded-lg p-1">
  <button className="rounded-sm px-2 py-1.5">Edit</button>
</div>
```

## Shadow scale [#shadow-scale]

Shadows are soft and low-alpha: they hint at height instead of shouting it. The
higher something floats, the bigger its shadow. Flip to dark mode and they almost
vanish. That's on purpose, see below.

## Where things live [#where-things-live]

Each level has its own surface, radius and shadow. In light mode the shadow
carries the depth. In dark mode shadows disappear, so each layer gets lighter
instead: `background` → `card` → `popover`. Dialogs share one scrim from
`modal-scrim.ts`, so every modal dims the page the same way.

| Level             | Surface      | Radius       | Shadow                 |
| ----------------- | ------------ | ------------ | ---------------------- |
| Controls          | `bg-card`    | `rounded-md` | `shadow-xs`            |
| Cards             | `bg-card`    | `rounded-xl` | `shadow-xs` + `ring-1` |
| Menus and selects | `bg-popover` | `rounded-lg` | `shadow-lg` + `ring-1` |
| Popovers          | `bg-popover` | `rounded-xl` | `shadow-lg` + `ring-1` |
| Dialogs           | `bg-popover` | `rounded-xl` | `shadow-xl` + scrim    |

## Border or shadow? [#border-or-shadow]

Content that stays in the page flow gets a hairline `border`. Anything that
floats above it gets a shadow and a faint `ring-1 ring-foreground/10`, so it
still has an edge in dark mode.

## Related [#related]

# Emoji & Icon Picker (/docs/ui/emoji-icon-picker)

## Preview [#preview]

## Usage [#usage]

The field stores the serialized string, so a plain `z.string()` does the job.

```ts
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormEmojiIcon } from '@vitnode/core/components/form/fields/emoji-icon'
import { EMOJI_ICON_MAX_LENGTH } from '@vitnode/core/lib/emoji-icon'

const formSchema = z.object({
  prefix: z.string().max(EMOJI_ICON_MAX_LENGTH).default(''),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'prefix',
      component: (props) => (
        <AutoFormEmojiIcon {...props} allowRemove label="Prefix" />
      ),
    },
  ]}
/>
```

</Tab>

```tsx
import { EmojiIconPicker } from '@vitnode/core/components/ui/emoji-icon-picker'
import type { EmojiIconValue } from '@vitnode/core/lib/emoji-icon'

const [icon, setIcon] = useState<EmojiIconValue | undefined>()

<EmojiIconPicker allowRemove onChange={setIcon} value={icon} />
```

</Tab>

</Tabs>

## The value [#the-value]

```ts
type EmojiIconValue =
  { type: 'emoji'; value: string } | { type: 'icon'; value: string }
```

An emoji value is the character (`🚀`). An icon value is a kebab-case
[Lucide](https://lucide.dev/icons) name (`shield-check`), readable in the
database and portable to any Lucide renderer.

For storage, serialize it to `emoji:🚀` or `icon:rocket`. It fits a
`varchar(64)` column.

```ts
import {
  parseEmojiIcon,
  serializeEmojiIcon,
} from '@vitnode/core/lib/emoji-icon'

serializeEmojiIcon({ type: 'icon', value: 'rocket' })
parseEmojiIcon('emoji:🚀')
parseEmojiIcon('icon:../../etc/passwd')
```

These return `"icon:rocket"`, `{ type: 'emoji', value: '🚀' }` and `undefined`.
`parseEmojiIcon` is also the validator: anything that isn't exactly one emoji or
one icon name comes back `undefined`.

<Callout type="warn" title="Validate on the server too">
  The picker only produces valid values. A request body can say anything, so
  parse it before you write it:

```ts
prefix: serializeEmojiIcon(parseEmojiIcon(body.prefix)) || null
```

</Callout>

## Rendering a stored value [#rendering-a-stored-value]

`EmojiIcon` renders a parsed value: a glyph for an emoji, an SVG for an icon.
An invalid value renders nothing.

```tsx
import { EmojiIcon } from '@vitnode/core/components/ui/emoji-icon'

;<EmojiIcon value={parseEmojiIcon(role.prefix)} />
```

Only icon names? Use [`DynamicIcon`](/docs/ui/icons#icons-by-name). Icons
rendered on the server arrive in the first HTML, and the browser never ships the
whole icon library. That needs one line in `getRouter()`, already in the
scaffold:

```tsx title="src/router.tsx"
import { setupLucideIconSsr } from '@vitnode/core/tanstack/icons'

setupLucideIconSsr({ router })
```

Without it, `DynamicIcon` still works but loads icons in the browser after the
page renders.

Both are `aria-hidden`, since they decorate nearby text. An icon-only control
needs its own `aria-label`.

## Role prefixes [#role-prefixes]

A role's **Prefix** field (General tab of its edit dialog) uses this picker. The
prefix shows before the role name and before every member's name wherever
`RoleFormat` or `UserFormat` renders. It arrives as `role.prefix`
(`null | string`), and both components parse it for you.

```tsx
<UserFormat format user={user} />
```

## Performance and keyboard [#performance-and-keyboard]

- Only the trigger ships with your page. Emoji data loads when the popover
  opens, and the ~1750 icons load only when someone opens the **Icon** tab.
- The icon grid is virtualized, so its size doesn't hurt scrolling.
- The grid is one tab stop. Arrows move (up and down jump a row),
  <kbd>Home</kbd> / <kbd>End</kbd> go to the row's ends, <kbd>Enter</kbd> or
  <kbd>Space</kbd> picks.
- The emoji picker here and in the editor toolbar share grid size, search and
  skin tone switch.

## Props [#props]

### EmojiIconPicker [#emojiiconpicker]

<TypeTable
  type={{
    value: {
      description: 'The current selection.',
      type: 'EmojiIconValue | undefined',
      default: 'undefined',
    },
    onChange: {
      description:
        'Called with the new selection, or `undefined` when cleared. Picking closes the popover.',
      type: '(value: EmojiIconValue | undefined) => void',
      required: true,
    },
    allow: {
      description: 'Which tabs to offer. One kind shows that picker alone.',
      type: "readonly ('emoji' | 'icon')[]",
      default: "['emoji', 'icon']",
    },
    allowRemove: {
      description: 'Shows a clear button once something is picked.',
      type: 'boolean',
      default: 'false',
    },
    placeholder: {
      description: 'Trigger text while nothing is picked.',
      type: 'string',
      default: '"Pick an emoji or icon"',
    },
  }}
/>

Other `button` props go to the trigger. `AutoFormEmojiIcon` takes the same props
except `value` and `onChange`.

### EmojiPicker and IconPicker [#emojipicker-and-iconpicker]

The bare panels, with no popover or trigger. Drop them into a dialog, sidebar or
toolbar.

```tsx
import { EmojiPicker } from '@vitnode/core/components/ui/emoji-picker'
import { IconPicker } from '@vitnode/core/components/ui/icon-picker'

;<IconPicker onSelect={setIcon} value={icon} />
```

<TypeTable
  type={{
    onSelect: {
      description: 'Called with the emoji character or the Lucide icon name.',
      type: '(value: string) => void',
      required: true,
    },
    value: {
      description: 'IconPicker only. Highlights the current icon.',
      type: 'string',
    },
    height: {
      description: 'Height of the scrollable list, in pixels.',
      type: 'number',
      default: '288',
    },
    autoFocus: {
      description: 'Focuses the search input on mount.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

# Empty (/docs/ui/empty)

## Usage [#usage]

```ts
import {
  Empty,
  EmptyContent,
  EmptyDescription,
  EmptyHeader,
  EmptyMedia,
  EmptyTitle,
} from '@vitnode/core/components/ui/empty'
```

```tsx
<Empty>
  <EmptyHeader>
    <EmptyMedia variant="icon">
      <FolderCode />
    </EmptyMedia>
    <EmptyTitle>No projects yet</EmptyTitle>
    <EmptyDescription>
      Start a fresh one or import a repository.
    </EmptyDescription>
  </EmptyHeader>
  <EmptyContent>
    <Button>Create project</Button>
  </EmptyContent>
</Empty>
```

Use it wherever a screen would otherwise show nothing: a blank table, a fresh
dashboard, a search with zero hits.

- `Empty` centers everything and fills its parent (`flex-1`).
- `EmptyHeader` groups media, title and description.
- `EmptyDescription` says why it's empty. Links inside get underlined.
- `EmptyContent` holds actions, a search box or anything clickable.

## Media [#media]

`variant="icon"` puts the icon on a muted tile and sizes it. The `default`
variant adds no styles, so use it for avatars and illustrations.

```tsx
<EmptyMedia>
  <Avatar size="lg">
    <AvatarImage alt="" src={user.avatar} />
    <AvatarFallback>AL</AvatarFallback>
  </Avatar>
</EmptyMedia>
```

## Outline [#outline]

The dashed border style is built in. Add `border` for a drop-zone look, or
`border-2` when it sits alone on a page.

```tsx
<Empty className="border">...</Empty>
```

## No results [#no-results]

A search miss is not the same as "no data yet". Echo the query back and offer a
way out.

```tsx
<EmptyDescription>Nothing matches "{query}".</EmptyDescription>
<EmptyContent>
  <Button onClick={() => setQuery('')} size="sm" variant="outline">
    Clear search
  </Button>
</EmptyContent>
```

## Compact [#compact]

The default padding is `p-6 md:p-12`. In a card, sidebar or popover, keep it at
`p-6` and shrink the text.

```tsx
<Empty className="p-6">
  <EmptyHeader>
    <EmptyTitle className="text-sm">No widgets yet</EmptyTitle>
    <EmptyDescription className="text-xs">
      Widgets from your plugins will show up here.
    </EmptyDescription>
  </EmptyHeader>
</Empty>
```

## Writing tips [#writing-tips]

- **Say what's missing.** "No projects yet" beats "Nothing here".
- **Say why.** Brand new, filtered out, or a search miss?
- **Give one next step.** If there's nothing to do, a clear description is
  enough.
- **Keep it short.** Nobody reads an essay about an empty table.
- **Skip the blame.** "No results for 'xylphone'", not "You typed it wrong".

## Accessibility [#accessibility]

- `EmptyTitle` renders an `h3`. Match your outline with `render={<h2 />}`, or
  use `render={<p />}` inside a small widget that shouldn't add a heading.
- Icons and avatars are decorative, since the title says what's missing. Use
  `alt=""` on images.
- When results change as the user types, announce the count in a
  `role="status"` region, like an `sr-only` paragraph.

## Props [#props]

All parts take regular `div` props. `EmptyTitle` takes `h3` props plus
`render`.

### EmptyMedia [#emptymedia]

## API Reference [#api-reference]

[shadcn/ui - Empty](https://ui.shadcn.com/docs/components/base/empty)

# Field (/docs/ui/field)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from '@vitnode/core/components/ui/field'
```

```tsx
<Field>
  <FieldLabel htmlFor="username">Username</FieldLabel>
  <Input id="username" />
  <FieldDescription>Pick something your friends can type.</FieldDescription>
</Field>
```

<Callout>
  Building a form? Use [AutoForm](/docs/ui/auto-form). It already renders every
  field with these parts, ids and ARIA included. Reach for `Field` in [custom
  AutoForm fields](#inside-a-custom-autoform-field) and settings that save
  instantly.
</Callout>

## Anatomy [#anatomy]

| Component          | Renders                                                            |
| ------------------ | ------------------------------------------------------------------ |
| `FieldSet`         | A `<fieldset>` grouping related fields.                            |
| `FieldLegend`      | The fieldset's `<legend>`. `variant="label"` makes it label-sized. |
| `FieldGroup`       | A stack of fields with even spacing. Enables `responsive`.         |
| `Field`            | One control with its label, description and error.                 |
| `FieldContent`     | Keeps a label and description together beside a control.           |
| `FieldLabel`       | The control's `<label>`. Wrap a `Field` in it for a choice card.   |
| `FieldTitle`       | A label-styled title for content already inside a `FieldLabel`.    |
| `FieldDescription` | Muted helper text.                                                 |
| `FieldError`       | An error message with `role="alert"`.                              |
| `FieldSeparator`   | A divider, optionally with text in the middle.                     |

## Orientation [#orientation]

`Field` is vertical by default. Use `horizontal` for checkboxes and switches.
The markup order decides the side: control first puts it on the left.

```tsx
<Field orientation="horizontal">
  <FieldContent>
    <FieldLabel htmlFor="digest">Weekly digest</FieldLabel>
    <FieldDescription>A short recap, every Monday.</FieldDescription>
  </FieldContent>
  <Switch id="digest" />
</Field>
```

### Responsive [#responsive]

`responsive` stacks on narrow screens and goes side by side once its
`FieldGroup` is wide enough. It's a container query, so it follows the group's
width, not the window's.

```tsx
<FieldGroup>
  <Field orientation="responsive">
    <FieldContent>
      <FieldLabel htmlFor="name">Display name</FieldLabel>
      <FieldDescription>Shown next to your posts.</FieldDescription>
    </FieldContent>
    <Input id="name" />
  </Field>
</FieldGroup>
```

## Fieldset and legend [#fieldset-and-legend]

Screen readers read the legend before each field inside, so "Mentions" becomes
"Notifications, Mentions". Free context, zero extra pixels.

```tsx
<FieldSet>
  <FieldLegend>Notifications</FieldLegend>
  <FieldGroup>
    <Field orientation="horizontal">
      <Checkbox id="mentions" />
      <FieldLabel htmlFor="mentions">Mentions</FieldLabel>
    </Field>
    <FieldSeparator>or</FieldSeparator>
    <Field>
      <FieldLabel htmlFor="backup-email">Backup email</FieldLabel>
      <Input id="backup-email" type="email" />
    </Field>
  </FieldGroup>
</FieldSet>
```

## Choice cards [#choice-cards]

Wrap a `Field` in a `FieldLabel` and the whole card becomes clickable. It
highlights when checked and shows a focus ring. Use `FieldTitle` inside, since
you're already in a label.

```tsx
<RadioGroup defaultValue="team">
  <FieldLabel htmlFor="plan-team">
    <Field orientation="horizontal">
      <FieldContent>
        <FieldTitle>Team</FieldTitle>
        <FieldDescription>
          Shared workspaces for up to 20 people.
        </FieldDescription>
      </FieldContent>
      <RadioGroupItem id="plan-team" value="team" />
    </Field>
  </FieldLabel>
</RadioGroup>
```

To disable a card, put `data-disabled` on the `Field` and `disabled` on the
control. AutoForm's [Radio Group](/docs/ui/radio-group#blocks) uses this for
`variant="blocks"`.

## Errors [#errors]

Set `data-invalid` on the field, `aria-invalid` on the control, and point
`aria-describedby` at the `FieldError`. The preview above shows it live.

```tsx
<Field data-invalid={isInvalid}>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input aria-describedby="email-error" aria-invalid={isInvalid} id="email" />
  {isInvalid && <FieldError id="email-error">That is not an email.</FieldError>}
</Field>
```

`FieldError` also takes `errors`. It drops duplicates, shows one message as
text and several as a list, and renders nothing when empty.

```tsx
<FieldError errors={[{ message: 'Too short' }, { message: 'Too short' }]} />
```

## Inside a custom AutoForm field [#inside-a-custom-autoform-field]

Mix `Field` with AutoForm's parts and your field matches the built-in ones:

- `AutoFormLabel` is a `FieldLabel` pointed at the control, with the "Optional" hint.
- `AutoFormDesc` renders the description.
- `FormControl` passes `id`, `aria-invalid` and `aria-describedby` to its child.
- `FormMessage` is a `FieldError` with the field's validation errors.

```tsx
import type { ItemAutoFormComponentProps } from '@vitnode/core/components/form/auto-form'
import { AutoFormDesc } from '@vitnode/core/components/form/common/desc'
import { AutoFormLabel } from '@vitnode/core/components/form/common/label'
import { Field, FieldContent } from '@vitnode/core/components/ui/field'
import { FormControl, FormMessage } from '@vitnode/core/components/ui/form'
import { Switch } from '@vitnode/core/components/ui/switch'

export const AutoFormSettingSwitch = ({
  label,
  description,
  field,
  otherProps: { isOptional },
}: ItemAutoFormComponentProps) => (
  <>
    <Field orientation="horizontal">
      <FieldContent>
        {label && (
          <AutoFormLabel isOptional={isOptional}>{label}</AutoFormLabel>
        )}
        {description && <AutoFormDesc>{description}</AutoFormDesc>}
      </FieldContent>
      <FormControl>
        <Switch
          checked={field.value ?? false}
          onCheckedChange={field.onChange}
        />
      </FormControl>
    </Field>
    <FormMessage />
  </>
)
```

Use it like any field: `component: props => <AutoFormSettingSwitch {...props} label="Weekly digest" />`.

## Accessibility [#accessibility]

- Give every control an `id` and its `FieldLabel` a matching `htmlFor`. Clicking
  the label then focuses or toggles the control.
- `Field` has `role="group"`, so control, label and help text are announced
  together.
- `FieldError` has `role="alert"`, so new messages are read out as they appear.
- Choice cards keep the real radio or checkbox inside. Tab, arrow keys and
  Space work as usual.

## Props [#props]

Every part accepts the props of the element it renders, plus:

## API Reference [#api-reference]

[shadcn/ui - Field](https://ui.shadcn.com/docs/components/base/field)

# Frame (/docs/ui/frame)

`Frame` groups related settings or facts under one title. The title sits on a
soft outer layer, and the rows sit on a raised inner panel. It is the card the
**Settings → Overview** page is built from.

## Usage [#usage]

```ts
import {
  Frame,
  FrameAction,
  FrameDescription,
  FrameFooter,
  FrameHeader,
  FramePanel,
  FrameTitle,
} from '@vitnode/core/components/ui/frame'
```

```tsx
<Frame>
  <FrameHeader>
    <FrameTitle render={<h2 />}>AI features</FrameTitle>
  </FrameHeader>
  <FramePanel>
    <Item>
      <ItemMedia aria-hidden variant="tile">
        <BotIcon />
      </ItemMedia>
      <ItemContent>
        <ItemTitle>
          Semantic search <Badge variant="outline">Smart</Badge>
        </ItemTitle>
        <ItemDescription>Find content by meaning, not exact wording.</ItemDescription>
      </ItemContent>
      <ItemActions>
        <Switch aria-label="Semantic search" />
      </ItemActions>
    </Item>
  </FramePanel>
</Frame>
```

- `FrameHeader` holds the title, an optional description and an optional action.
- `FramePanel` is the inner card. It draws a divider between its children, so
  you never add separators yourself.
- Rows are regular [Item](/docs/ui/item) components. Inside a panel they lose
  their own border and radius, so they line up edge to edge.
- `ItemMedia variant="tile"` gives the icon its small rounded square.

## Header description and action [#header-description-and-action]

Add `FrameDescription` under the title and put a button in `FrameAction`. The
action stays on the end side and centers against the title block.

```tsx
<FrameHeader>
  <FrameTitle render={<h2 />}>Publishing</FrameTitle>
  <FrameDescription>Where visitors find your site.</FrameDescription>
  <FrameAction>
    <Button size="sm" variant="ghost">
      Learn more
    </Button>
  </FrameAction>
</FrameHeader>
```

## Footer note [#footer-note]

Put a short note under the panel with `FrameFooter`. It sits on the outer
layer, so it reads as a remark about the whole group, not as another row.

```tsx
<Frame>
  <FrameHeader>...</FrameHeader>
  <FramePanel>...</FramePanel>
  <FrameFooter>A signed-out device has to sign in again.</FrameFooter>
</Frame>
```

## Side by side [#side-by-side]

Frames stretch to fill their grid cell, so two frames in a
`md:grid-cols-2` grid keep the same height even with different row counts.

```tsx
<div className="grid gap-4 md:grid-cols-2">
  <Frame>...</Frame>
  <Frame>...</Frame>
</div>
```

## Accessibility [#accessibility]

- `FrameTitle` renders a `div`. Pass `render={<h2 />}` (or the level that fits
  the page) so screen readers can jump between frames.
- For a list of rows, render the panel as a list and each row as an item:
  `<FramePanel render={<ul />}>` with `<Item render={<li />}>`.
- Icon tiles are decorative. Give `ItemMedia` `aria-hidden`.
- A switch or icon-only button in a row needs an `aria-label` that names the
  setting.

## Props [#props]

`Frame`, `FrameHeader`, `FrameDescription`, `FrameAction` and `FrameFooter`
take regular element props.

### FrameTitle and FramePanel [#frametitle-and-framepanel]

<TypeTable
  type={{
    render: {
      description: 'Replaces the `div`, such as with an `h2` or a `ul`.',
      type: 'ReactElement | ((props, state) => ReactElement)',
    },
  }}
/>

## API Reference [#api-reference]

[Base UI - useRender](https://base-ui.com/react/utils/use-render)

# useBeforeUnload (/docs/ui/hooks/use-before-unload)

## Preview [#preview]

## Usage [#usage]

```ts
import { useBeforeUnload } from '@vitnode/core/hooks/use-before-unload'
```

```tsx
const [isDirty, setIsDirty] = React.useState(false)

useBeforeUnload(isDirty)
```

While `enabled` is `true`, closing the tab, reloading or typing a new address
makes the browser ask "Leave site?". Set it back to `false` once the changes are
saved.

## Check at the last moment [#check-at-the-last-moment]

Pass a function and the hook calls it only when someone tries to leave. Handy
when the dirty state lives in a ref that doesn't re-render:

```tsx
const hasUnsavedChanges = React.useRef(false)

useBeforeUnload(() => hasUnsavedChanges.current)
```

## Good to know [#good-to-know]

- **The browser writes the message.** Modern browsers ignore custom text.
  `message` only matters for old ones.
- **In-app navigation isn't covered.** Clicking a router `Link` doesn't unload
  the page, so no prompt.
- **Use it sparingly.** A prompt on every page teaches people to click "Leave"
  without reading.

## Options [#options]

<TypeTable
  type={{
    enabled: {
      description:
        'Whether to warn. A function is called when someone tries to leave.',
      type: 'boolean | (() => boolean)',
      default: 'true',
    },
    message: {
      description: 'Text for older browsers. Modern browsers show their own.',
      type: 'string',
    },
  }}
/>

The hook returns nothing.

# useIntersectionObserver (/docs/ui/hooks/use-intersection-observer)

## Preview [#preview]

## Usage [#usage]

```ts
import { useIntersectionObserver } from '@vitnode/core/hooks/use-intersection-observer'
```

```tsx
const [element, setElement] = React.useState<HTMLDivElement | null>(null)
const entry = useIntersectionObserver(element, { threshold: 0.5 })

return (
  <div ref={setElement}>
    {entry?.isIntersecting ? 'I can see you!' : 'Nobody is looking...'}
  </div>
)
```

It returns the latest
[`IntersectionObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry),
or `undefined` until the first report. On the server, and in browsers without
`IntersectionObserver`, it stays `undefined`.

Keep the element in state through a callback ref, not `useRef`. Then the hook
notices when the node mounts late or gets swapped.

## Load once, then stop [#load-once-then-stop]

`freezeOnceVisible` stops observing the first time the element shows up. A
positive `rootMargin` starts loading just before it reaches the screen.

```tsx
const entry = useIntersectionObserver(element, {
  freezeOnceVisible: true,
  rootMargin: '200px',
})

return (
  <div ref={setElement}>{entry?.isIntersecting ? <HeavyChart /> : null}</div>
)
```

## Inside a scroll container [#inside-a-scroll-container]

The preview above watches its own scroll box, not the viewport. Pass that box as
`root`, stored in state the same way:

```tsx
const [root, setRoot] = React.useState<HTMLDivElement | null>(null)
const entry = useIntersectionObserver(element, { root })
```

## Options [#options]

# useLocalStorage (/docs/ui/hooks/use-local-storage)

## Preview [#preview]

## Usage [#usage]

```ts
import { useLocalStorage } from '@vitnode/core/hooks/use-local-storage'
```

```tsx
const [name, setName] = useLocalStorage('name', '')

return <input onChange={(e) => setName(e.target.value)} value={name} />
```

Pass a key and a default, get the value and a setter, just like `useState`.
Values are stored as JSON, so numbers, booleans, arrays and plain objects come
back as you saved them.

## Update and reset [#update-and-reset]

The setter takes a function that gets the freshest value. The third item
removes the key and falls back to the default.

```ts
const [count, setCount, resetCount] = useLocalStorage('count', 0)

setCount((previous) => previous + 1)
resetCount()
```

## Good to know [#good-to-know]

- **Synced everywhere.** Every component using the same key updates together,
  in this tab and in other tabs.
- **Server-safe.** The server renders the default, then the browser switches to
  the stored value without a hydration mismatch.
- **No crashes.** A broken stored value falls back to the default. Blocked or
  full storage keeps the value in memory for the session.
- **Nice-to-haves only.** Storage lives in one browser on one device. Use it for
  a collapsed panel or a draft, never for data the server needs.

## Returns [#returns]

<TypeTable
  type={{
    '[0] value': {
      description: 'The stored value, or the default.',
      type: 'T',
    },
    '[1] setValue': {
      description: 'Saves a value, or a function of the previous one.',
      type: '(value: T | ((previous: T) => T)) => void',
    },
    '[2] removeValue': {
      description: 'Removes the key and goes back to the default.',
      type: '() => void',
    },
  }}
/>

# useIsMobile (/docs/ui/hooks/use-mobile)

## Preview [#preview]

## Usage [#usage]

```ts
import { useIsMobile } from '@vitnode/core/hooks/use-mobile'
```

```tsx
const isMobile = useIsMobile()

return isMobile ? <PostActionsDrawer /> : <PostActionsDropdown />
```

It returns `true` below **768px**, where Tailwind's `md:` starts, and updates
live on resize or rotation.

## Prefer CSS for layout [#prefer-css-for-layout]

If only the look changes, use responsive classes. CSS is right on the first
paint and needs no JavaScript:

```tsx
<div className="flex flex-col gap-4 md:flex-row">...</div>
```

Reach for the hook when the **behavior** changes: a
[Drawer](/docs/ui/drawer) instead of a [Dropdown Menu](/docs/ui/dropdown-menu),
skipping a heavy component, or loading fewer items.

## Server rendering [#server-rendering]

The server can't see the screen, so the hook returns `false` during SSR and
hydration, then switches without a mismatch warning. A phone may briefly see the
desktop version. Components that mount later in the browser get the real value
on their first render.

## Returns [#returns]

# useSlidingIndicator (/docs/ui/hooks/use-sliding-indicator)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  slidingIndicatorTransitionClassName,
  useSlidingIndicator,
} from '@vitnode/core/hooks/use-sliding-indicator'
```

```tsx
const [active, setActive] = React.useState(0)
const { containerRef, indicatorRef, isReady } =
  useSlidingIndicator<HTMLDivElement>(active)

return (
  <div
    className="bg-muted relative flex gap-1 rounded-lg p-1"
    ref={containerRef}
    role="group"
  >
    <span
      aria-hidden
      className={cn(
        'bg-background pointer-events-none absolute top-0 left-0 rounded-md opacity-0',
        isReady && slidingIndicatorTransitionClassName,
      )}
      ref={indicatorRef}
    />
    {filters.map((label, index) => (
      <button
        aria-pressed={active === index}
        className="relative rounded-md px-3 py-1.5 text-sm"
        data-sliding-indicator-item
        key={label}
        onClick={() => setActive(index)}
        type="button"
      >
        {label}
      </button>
    ))}
  </div>
)
```

Mark every item with `data-sliding-indicator-item` and pass the active index.
The hook sizes and moves the indicator to sit behind that item. VitNode's theme
switcher and mobile navigation bar work this way.

## Styling checklist [#styling-checklist]

- The container is `relative`. The indicator is `absolute top-0 left-0` and
  starts at `opacity-0`. The hook sets its size, position and opacity.
- Items are `relative`, so they sit above the indicator.
- The indicator is `aria-hidden`. Put the active state on the items with
  `aria-pressed`, `aria-selected` or `aria-current`.

## How it behaves [#how-it-behaves]

- **Follows resizes.** A `ResizeObserver` on the container repositions the
  indicator, for example when labels change language.
- **No slide on first render.** `isReady` turns `true` one frame after mount.
  Add the transition class only then, or the indicator flies in from the corner.
- **Hides when nothing is active.** An index with no matching item, like `-1`,
  hides the indicator.
- **Respects reduced motion.** The transition class slides for 300ms on
  `ease-fluid` and turns off under `prefers-reduced-motion`.

## API [#api]

Returns:

<TypeTable
  type={{
    containerRef: {
      description: 'Ref for the element wrapping the items and the indicator.',
      type: 'React.RefObject<Container | null>',
    },
    indicatorRef: {
      description: 'Ref for the indicator element.',
      type: 'React.RefObject<HTMLSpanElement | null>',
    },
    isReady: {
      description:
        'True one frame after mount. Gate the transition class on it.',
      type: 'boolean',
    },
  }}
/>

# Hover Card (/docs/ui/hover-card)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from '@vitnode/core/components/ui/hover-card'
```

```tsx
<HoverCard>
  <HoverCardTrigger href="/profile/axendev">@axendev</HoverCardTrigger>
  <HoverCardContent>Creator of VitNode.</HoverCardContent>
</HoverCard>
```

`HoverCardTrigger` renders a real link, so give it an `href`. Clicking it goes
there like any other link.

## Inside text [#inside-text]

Mentions and thread links in a post are the classic use. The card opens after
600ms and closes 300ms after you leave. Tune both on the trigger.

```tsx
<HoverCardTrigger closeDelay={100} delay={200} href="/profile/maya">
  @maya
</HoverCardTrigger>
```

## Accessibility [#accessibility]

- Keyboard focus opens the card too.
- Touch screens have no hover, so the card never shows there. Keep it a bonus:
  everything in it must also live on the page the link opens.
- Don't put buttons or forms in it. Use a [Popover](/docs/ui/popover) for
  anything interactive.

## Props [#props]

`HoverCardContent` takes `side` (default `bottom`), `align` (default
`center`), `sideOffset` (default `4`), `alignOffset` (default `0`) and
`anchor`, like a [Popover](/docs/ui/popover). It's `w-64` by default.

## API Reference [#api-reference]

[Base UI - Preview Card](https://base-ui.com/react/components/preview-card#api-reference)

# Icons (/docs/ui/icons)

VitNode uses [lucide-react](https://lucide.dev/icons) for icons: over 1,500
outlined icons with one stroke style. Components size them for you, so most of
the time you just drop one in.

## Size scale [#size-scale]

`size-4` is the default. It matches `text-sm`, the size of buttons, menus and
inputs. Go up for navigation and empty states, down for badges.

## Icons in components [#icons-in-components]

Buttons, badges and input groups size any child `svg` that has no `size-*`
class. Add `data-icon="inline-start"` or `"inline-end"` so the button trims
its padding on that side.

```tsx
<Button>
  <PlusIcon data-icon="inline-start" />
  New post
</Button>
```

## Stroke [#stroke]

Keep the default `strokeWidth={2}`. It sits right next to `font-medium` text.
Thinner or bolder strokes are for big hero icons, not your toolbar.

## Icons by name [#icons-by-name]

Store an icon as a string and render it with `DynamicIcon`. Each icon loads on
its own, and icons rendered on the server arrive with the page, so nothing pops
in. An unknown name renders nothing.

```tsx
import { DynamicIcon } from '@vitnode/core/components/ui/dynamic-icon'

<DynamicIcon className="size-5" name="shield-check" />
```

Letting users pick one? The [Emoji & Icon Picker](/docs/ui/emoji-icon-picker)
returns exactly this name.

## Do and don't [#do-and-dont]

- Lucide hides icons from screen readers by default (`aria-hidden="true"`), so
  an icon next to text needs nothing extra.
- Icon-only buttons need an `aria-label`. TypeScript asks for it on `size="icon"`.
- Lucide has no brand logos. Use an inline SVG with `fill="currentColor"` and
  `aria-hidden`.

## Related [#related]

# Image Zoom (/docs/ui/image-zoom)

## Preview [#preview]

## Usage [#usage]

```ts
import { ImageZoom } from '@vitnode/core/components/ui/image-zoom'
```

```tsx
<ImageZoom
  alt="The VitNode AdminCP dashboard"
  imageClassName="w-full rounded-md border"
  src="/screenshots/dashboard.webp"
/>
```

Click the image, or focus it and press <kbd>Enter</kbd>, and it glides to the
middle of the screen. Click anywhere, press <kbd>Escape</kbd> or hit × to send
it back.

## Drag to dismiss [#drag-to-dismiss]

Grab the zoomed image and drag or flick it in any direction to close. Let go
early and it springs back to the middle. The backdrop fades as you drag, so you
can see where you're headed.

## Sharper zoom [#sharper-zoom]

Show a light thumbnail and load the big file only on zoom:

```tsx
<ImageZoom
  alt="The VitNode AdminCP dashboard"
  src={thumbnail}
  zoomSrc={fullSize}
/>
```

## Styling [#styling]

- `className` styles the clickable wrapper. Use it for layout and visibility,
  like `hidden dark:block` for theme-specific screenshots.
- `imageClassName` styles the image on the page.

The zoomed image always fits the screen without cropping.

## Accessibility [#accessibility]

- The image is a real button that opens a dialog.
- `alt` is required. It labels the image and names the zoomed view.
- Focus is trapped while zoomed and returns to the image on close.
- Reduced motion zooms instantly. Reduced transparency swaps the blurred
  backdrop for a solid one.

## Props [#props]

# Introduction (/docs/ui)

VitNode UI is the component library behind every VitNode screen, from the
AdminCP to your plugin pages. It gives you buttons, dialogs, forms, tables
and around seventy other pieces that share one set of colors, type, spacing and
motion, so a plugin looks like it belongs without extra effort.

## Use a component [#use-a-component]

Every component lives in `@vitnode/core`, which your app already depends on.
Import it from `@vitnode/core/components/ui/<name>`:

```tsx
import { Button } from '@vitnode/core/components/ui/button'

export const PublishButton = () => <Button>Publish post</Button>
```

There's nothing to install and no copy-paste step. Components are styled with
[design tokens](#foundations), so they follow your theme and switch to dark
mode automatically.

## What it's built on [#what-its-built-on]

- **[Base UI](https://base-ui.com)** (`@base-ui/react`) for the behavior:
  focus management, keyboard support, ARIA and positioning.
- **[shadcn/ui](https://ui.shadcn.com)** in its `base-vega` style for the
  starting point of each component's look.
- **[Tailwind CSS v4](https://tailwindcss.com)** for styling, driven by CSS
  variables.
- **[Motion](https://motion.dev)** for the few animations that need springs,
  like rolling numbers, the switch thumb and image zoom.

## Design principles [#design-principles]

Inspired by Apple's Human Interface Guidelines (we're not affiliated, we just
like how their stuff feels):

- **Respond on press.** Everything reacts the moment your pointer goes down.
  [Motion](/docs/ui/motion)
- **Move with purpose.** Short, interruptible, no bounce for fun.
  [Motion](/docs/ui/motion)
- **Respect people's settings.** Reduced motion, reduced transparency and
  touch-sized targets. [Accessibility](/docs/ui/accessibility)
- **Sweat the details.** Steady numbers and nested corners.
  [Typography](/docs/ui/typography) · [Radius & Elevation](/docs/ui/elevation)

## Foundations [#foundations]

Components never hardcode a color, size or curve. They read shared tokens from
your app's `src/styles.css`, and each foundation has its own page full of live
examples.

<Cards>
  <Card
    icon={<Palette />}
    title="Colors"
    href="/docs/ui/colors"
    description="Semantic OKLCH tokens for surfaces, brand, status and charts."
  />
  <Card
    icon={<Type />}
    title="Typography"
    href="/docs/ui/typography"
    description="System font, type scale with built-in tracking, hierarchy."
  />
  <Card
    icon={<Waves />}
    title="Motion"
    href="/docs/ui/motion"
    description="Press feedback, interruptible transitions, springs, reduced motion."
  />
  <Card
    icon={<Ruler />}
    title="Spacing & Layout"
    href="/docs/ui/spacing"
    description="Spacing scale, gap rules, breakpoints and line length."
  />
  <Card
    icon={<Layers />}
    title="Radius & Elevation"
    href="/docs/ui/elevation"
    description="One radius variable, concentric corners and soft shadows."
  />
  <Card
    icon={<Shapes />}
    title="Icons"
    href="/docs/ui/icons"
    description="Lucide sizes, icons in buttons, labels and brand logos."
  />
  <Card
    icon={<Accessibility />}
    title="Accessibility"
    href="/docs/ui/accessibility"
    description="Focus rings, touch targets, contrast and announcements."
  />
</Cards>

## Popular components [#popular-components]

# Input Group (/docs/ui/input-group)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  InputGroup,
  InputGroupAddon,
  InputGroupButton,
  InputGroupInput,
  InputGroupText,
  InputGroupTextarea,
} from '@vitnode/core/components/ui/input-group'
```

```tsx
<InputGroup>
  <InputGroupInput aria-label="Search" placeholder="Search..." />
  <InputGroupAddon>
    <Search />
  </InputGroupAddon>
  <InputGroupAddon align="inline-end">12 results</InputGroupAddon>
</InputGroup>
```

Put the control first and the addons after it. `align` moves each addon into
place, whatever the markup order.

## Addons [#addons]

An addon holds an icon, `InputGroupText`, a [`Kbd`](/docs/ui/kbd) or an
`InputGroupButton`. Icon-only buttons need an `aria-label`. Clicking an addon
outside its buttons focuses the control.

```tsx
<InputGroup>
  <InputGroupInput aria-label="Invite link" readOnly value={inviteUrl} />
  <InputGroupAddon align="inline-end">
    <InputGroupButton aria-label="Copy invite link" size="icon-xs">
      <Copy />
    </InputGroupButton>
  </InputGroupAddon>
</InputGroup>
```

Disable the control and the whole group dims with it.

## Alignment [#alignment]

| `align`                  | Position                                |
| ------------------------ | --------------------------------------- |
| `inline-start` (default) | Before the text                         |
| `inline-end`             | After the text                          |
| `block-start`            | Above the control, full width           |
| `block-end`              | Below the control, full width (footers) |

```tsx
<InputGroup>
  <InputGroupTextarea aria-label="Describe the issue" rows={6} />
  <InputGroupAddon align="block-end">
    <InputGroupText className="tabular-nums">
      0 of 500 characters
    </InputGroupText>
  </InputGroupAddon>
</InputGroup>
```

## With AutoForm [#with-autoform]

Pass addons as children of `AutoFormInput` or `AutoFormTextarea`. The field
wraps itself in an `InputGroup`.

```tsx
{
  id: "description",
  component: props => (
    <AutoFormTextarea {...props} label="Description" rows={6}>
      <InputGroupAddon align="block-end">
        <InputGroupText className="tabular-nums">
          {props.field.value?.toString().length ?? 0} of 500 characters
        </InputGroupText>
      </InputGroupAddon>
    </AutoFormTextarea>
  ),
}
```

## Button sizes [#button-sizes]

`InputGroupButton` defaults to `variant="ghost"` and `type="button"`. Sizes:
`xs` (default), `sm`, `icon-xs` and `icon-sm`. All fit the default group height.

## API Reference [#api-reference]

[shadcn/ui - Input Group](https://ui.shadcn.com/docs/components/base/input-group)

# Input OTP (/docs/ui/input-otp)

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormInputOTP } from '@vitnode/core/components/form/fields/input-otp'
```

```tsx
const formSchema = z.object({
  code: z.string().length(6, 'Enter all 6 digits').regex(/^\d+$/, 'Only digits, please'),
})

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'code',
      component: props => (
        <AutoFormInputOTP
          {...props}
          description="We sent a 6-digit code to your email."
          label="Verify your account"
        />
      ),
    },
  ]}
/>
```

`.length(6)` sets the slot count and `.regex()` becomes the `pattern`.

</Tab>

```ts
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSeparator,
  InputOTPSlot,
} from '@vitnode/core/components/ui/input-otp'
```

```tsx
<InputOTP maxLength={6} onChange={setValue} value={value}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
  </InputOTPGroup>
  <InputOTPSeparator />
  <InputOTPGroup>
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>
```

</Tab>
</Tabs>

One real `<input>` sits underneath, so paste, password managers and SMS
autofill just work.

## Groups and patterns [#groups-and-patterns]

`AutoFormInputOTP` halves even codes of 6+ characters and keeps the rest in
one group. Pass `groups` to choose.

```tsx
<AutoFormInputOTP {...props} groups={[2, 2, 2]} label="Backup code" />
```

Without a schema, set `pattern`. Common regexes are re-exported:

```ts
import { REGEXP_ONLY_DIGITS } from '@vitnode/core/components/ui/input-otp'
```

```tsx
<InputOTP maxLength={4} pattern={REGEXP_ONLY_DIGITS}>
  …
</InputOTP>
```

`REGEXP_ONLY_CHARS` and `REGEXP_ONLY_DIGITS_AND_CHARS` too.

## Submit when complete [#submit-when-complete]

`onComplete` fires when every slot is filled, on both components.

```tsx
<AutoFormInputOTP {...props} onComplete={(code) => verify(code)} />
```

## Wrong code [#wrong-code]

A wrong code comes from your API. `setFormFieldError` turns every slot red
and shows the message. Try it in the [preview](#preview).

```ts
import { setFormFieldError } from '@vitnode/core/components/ui/form'
```

```tsx
<AutoForm
  formSchema={formSchema}
  onSubmit={async (values, form) => {
    const res = await verifyCode(values.code)
    if (!res.ok) setFormFieldError(form, 'code', "That code doesn't match.")
  }}
  fields={[...]}
/>
```

## Accessibility [#accessibility]

- `AutoFormInputOTP` wires the label, description and error to the input.
- With `InputOTP` alone, add an `id` and a `<Label htmlFor>`. Link help text
  and errors with `aria-describedby`, and set `aria-invalid` on errors.
- Slots are hidden from screen readers, so no digit is read twice.
- Characters animate in, except with reduced motion.

## Props [#props]

`AutoFormInputOTP` takes every `InputOTP` prop except `value` and `children`,
plus:

<TypeTable
  type={{
    label: { description: 'Label above the slots.', type: 'ReactNode' },
    description: {
      description: 'Help text below the slots.',
      type: 'ReactNode',
    },
    groups: {
      description:
        'Slots per group. Default: two halves for even lengths of 6+, else one group.',
      type: 'number[]',
    },
    maxLength: {
      description:
        'Code length. Default: the schema `.length()` / `.max()`, then 6.',
      type: 'number',
    },
    onChange: {
      description: 'Called with the new value on every change.',
      type: '(value: string) => void',
    },
    onComplete: {
      description: 'Called once every slot is filled.',
      type: '(value: string) => void',
    },
    pattern: {
      description:
        'Regex the value must match. Default: the schema `.regex()`.',
      type: 'string',
    },
    disabled: { description: 'Disables the input.', type: 'boolean' },
  }}
/>

## API Reference [#api-reference]

[input-otp](https://github.com/guilhermerodz/input-otp)

# Input (/docs/ui/input)

## Preview [#preview]

## Usage [#usage]

```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormInput } from '@vitnode/core/components/form/fields/input'
import { z } from 'zod'

const formSchema = z.object({
  username: z
    .string()
    .min(3, 'Usernames need at least 3 characters')
    .default(''),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'username',
      component: (props) => (
        <AutoFormInput {...props} label="Username" autoComplete="username" />
      ),
    },
  ]}
/>
```

</Tab>
  <Tab value="Manual">

```tsx
import { Input } from '@vitnode/core/components/ui/input'
```

```tsx
<Input aria-label="Username" autoComplete="username" />
```

</Tab>
</Tabs>

## States [#states]

Set `aria-invalid` for the error style and `disabled` to dim it. `type="file"`
gets a styled picker button. Wrap it in a [Field](/docs/ui/field) for the
label, description and error.

```tsx
<Input aria-invalid aria-describedby="email-error" id="email" type="email" />
```

## Addons [#addons]

Pass `InputGroupAddon` children to `AutoFormInput` and it renders an
[Input Group](/docs/ui/input-group): icons, prefixes, buttons.

```tsx
<AutoFormInput {...props} label="Search">
  <InputGroupAddon>
    <Search />
  </InputGroupAddon>
</AutoFormInput>
```

## Multi-language [#multi-language]

`multiLang` collects one value per enabled language. A language select appears
inside the input when there's more than one.

```ts
import { multiLangValueSchema } from '@vitnode/core/lib/helpers/multi-lang'

const formSchema = z.object({
  name: multiLangValueSchema({ minLength: 1, maxLength: 255 }).min(1),
})
```

```tsx
<AutoFormInput {...props} label="Name" multiLang />
```

The value is `{ languageCode, value }[]`. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields)
for saving it.

## Props [#props]

`AutoFormInput` also accepts every native `<input>` prop.

# Item (/docs/ui/item)

## Usage [#usage]

```ts
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from '@vitnode/core/components/ui/item'
```

```tsx
<Item variant="outline">
  <ItemMedia variant="icon">
    <ShieldCheck />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Two-factor authentication</ItemTitle>
    <ItemDescription>Add a second lock to your account.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <Button size="sm" variant="outline">
      Enable
    </Button>
  </ItemActions>
</Item>
```

Every app grows a dozen "icon, text, button on the right" rows. `Item` is that
row, built once.

- `ItemContent` stacks title and description and takes the free space.
- `ItemTitle` is one line and truncates.
- `ItemDescription` shows up to two muted lines. Links inside get underlined.
- `ItemActions` holds buttons, badges or a chevron at the end.

## Variants [#variants]

```tsx
<Item variant="muted">...</Item>
```

## Sizes [#sizes]

`sm` and `xs` shrink padding and gaps. Image media shrinks too, and `xs` also
uses smaller description text.

```tsx
<Item size="sm">...</Item>
```

## Media [#media]

With a description present, media aligns to the top of the text.

```tsx
<ItemMedia variant="image">
  <img alt="" src="/cover.webp" />
</ItemMedia>
```

## As a link [#as-a-link]

Pass an element to `render`, such as an `<a>`, a router `Link` or a `<button>`.
Put the row's content inside it so the link wraps everything. Links get a hover
background.

```tsx
<Item
  render={
    <a href="/docs/ui/avatar">
      <ItemContent>
        <ItemTitle>Read the Avatar docs</ItemTitle>
      </ItemContent>
      <ItemActions>
        <ChevronRight aria-hidden className="size-4" />
      </ItemActions>
    </a>
  }
/>
```

## Groups [#groups]

`ItemGroup` stacks items. `ItemSeparator` draws a line between them.

```tsx
<ItemGroup aria-label="Team members">
  <Item role="listitem">...</Item>
  <ItemSeparator />
  <Item role="listitem">...</Item>
</ItemGroup>
```

## Header and footer [#header-and-footer]

`ItemHeader` and `ItemFooter` span the full width, above or below the content.

```tsx
<Item variant="outline">
  <ItemHeader>
    <Badge variant="success">Active</Badge>
  </ItemHeader>
  <ItemContent>...</ItemContent>
  <ItemFooter>
    <Button size="sm">Edit</Button>
  </ItemFooter>
</Item>
```

## Accessibility [#accessibility]

- `ItemGroup` has `role="list"`. Give each `Item` `role="listitem"` and the
  group an `aria-label`.
- One interactive element per row: either the whole row is a link or button,
  or it holds buttons in `ItemActions`. Never a button inside a link.
- Icon-only buttons need an `aria-label` that names the row, like "Invite Ada
  Lovelace", not "Invite".
- Decorative icons get `aria-hidden`. Links that open a new tab say so in
  `sr-only` text.
- Rows rendered as links or buttons show a focus ring.

## Props [#props]

### Item [#item]

<TypeTable
  type={{
    variant: {
      description: 'The look of the row.',
      type: 'default | outline | muted',
      default: 'default',
    },
    size: {
      description: 'Padding and gaps.',
      type: 'default | sm | xs',
      default: 'default',
    },
    render: {
      description: 'Replaces the `div`, such as with a link or button.',
      type: 'ReactElement | ((props, state) => ReactElement)',
    },
  }}
/>

### ItemMedia [#itemmedia]

## API Reference [#api-reference]

[Base UI - useRender](https://base-ui.com/react/utils/use-render)

# Kbd (/docs/ui/kbd)

## Preview [#preview]

## Usage [#usage]

```ts
import { Kbd, KbdGroup } from '@vitnode/core/components/ui/kbd'
```

```tsx
<Kbd>Esc</Kbd>
```

`Kbd` renders a real `<kbd>`, so browsers and assistive tech know it's a key.

## Shortcuts [#shortcuts]

`KbdGroup` wraps a combination. It's a `<kbd>` too, which is how HTML
describes a key combo.

```tsx
<KbdGroup>
  <Kbd>Ctrl</Kbd>
  <Kbd>K</Kbd>
</KbdGroup>
```

Want a visible plus? Hide it from screen readers, since they already hear two
keys:

```tsx
<KbdGroup>
  <Kbd>Ctrl</Kbd>
  <span aria-hidden="true">+</span>
  <Kbd>C</Kbd>
</KbdGroup>
```

## In buttons, tooltips and inputs [#in-buttons-tooltips-and-inputs]

`Kbd` sizes itself to fit small buttons. Inside a [Tooltip](/docs/ui/tooltip)
it switches to a translucent style that stays readable in both themes. Next to
an [Input Group](/docs/ui/input-group) addon, it makes the classic "press ⌘ K
to search" field. No props needed for any of them.

```tsx
<Button size="sm" variant="outline">
  Accept
  <Kbd>Enter</Kbd>
</Button>
```

## ⌘ on Mac, Ctrl everywhere else [#-on-mac-ctrl-everywhere-else]

Detect the platform on the client, but render the same thing on the server and
during hydration. `useSyncExternalStore` does both: its third argument is used
for the server and hydration, then React switches to the real value.

```tsx
const subscribeToNothing = () => () => {}

const useIsApple = () =>
  React.useSyncExternalStore(
    subscribeToNothing,
    () => /Mac|iPhone|iPad|iPod/.test(navigator.userAgent),
    () => true,
  )

const ModifierKey = () => (useIsApple() ? <Kbd>⌘</Kbd> : <Kbd>Ctrl</Kbd>)
```

## Accessibility [#accessibility]

- Keep the `<kbd>` element. A styled `<span>` doesn't say "this is a key".
- Screen readers announce ⌘ and ⇧ inconsistently. Pair each symbol with
  visually hidden text, since `aria-label` on a `<kbd>` isn't reliably read:

```tsx
  <Kbd title="Command">
    <span aria-hidden="true">⌘</span>
    <span className="sr-only">Command</span>
  </Kbd>
  ```

- `Kbd` is a hint, not a control (`pointer-events-none`, `select-none`). Put
  the action on a real button and listen for the key itself.
- Never make a shortcut the only way to do something.

## Props [#props]

Both components accept every native `<kbd>` prop.

<TypeTable
  type={{
    Kbd: {
      description: 'A single key. Renders `<kbd data-slot="kbd">`.',
      type: "React.ComponentProps<'kbd'>",
    },
    KbdGroup: {
      description: 'A key combination. Renders `<kbd data-slot="kbd-group">`.',
      type: "React.ComponentProps<'kbd'>",
    },
  }}
/>

## API Reference [#api-reference]

[MDN - The Keyboard Input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/kbd)

# Label (/docs/ui/label)

## Preview [#preview]

## Usage [#usage]

```ts
import { Label } from '@vitnode/core/components/ui/label'
```

```tsx
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" />
```

`Label` is a styled native `<label>`. Point `htmlFor` at the control's `id`:
the label becomes a click target and screen readers read it on focus.

<Callout>
  [AutoForm](/docs/ui/auto-form) fields render their own label from the `label`
  prop. Don't add a `Label` next to one, or you'll get two. For a label with a
  description and error, use [Field](/docs/ui/field).
</Callout>

## With a checkbox [#with-a-checkbox]

Put the control first. Gap and alignment are built in.

```tsx
<div className="flex items-center gap-3">
  <Checkbox id="terms" />
  <Label htmlFor="terms">I promise I read the terms</Label>
</div>
```

## Wrapping the control [#wrapping-the-control]

No `id` handy? Wrap the control. A `<label>` names whatever is inside it.

```tsx
<Label>
  <Checkbox />
  Remember me
</Label>
```

## Disabled controls [#disabled-controls]

A disabled control dims its label and shows a `not-allowed` cursor, as in the
preview's last row.

```tsx
<div className="flex items-center gap-3">
  <Checkbox disabled id="newsletter" />
  <Label htmlFor="newsletter">Weekly newsletter (coming soon)</Label>
</div>
```

This needs the control **before** the label, as a sibling with the `peer`
class. `Checkbox`, `Switch` and `RadioGroupItem` already have it. Label
elsewhere? Put `group` and `data-disabled="true"` on a shared parent, which is
what [Field](/docs/ui/field) does.

## Accessibility [#accessibility]

- Always connect label and control, with `htmlFor` + `id` or by wrapping. A
  label merely next to an input is plain text to a screen reader.
- Placeholders are not labels. They vanish as soon as someone types.
- The label is part of the hit area, so keep it right next to small controls.

## Props [#props]

Accepts every native `<label>` prop.

## API Reference [#api-reference]

[MDN - The Label element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/label)

# Marker (/docs/ui/marker)

## Usage [#usage]

```ts
import {
  Marker,
  MarkerContent,
  MarkerIcon,
} from '@vitnode/core/components/ui/marker'
```

```tsx
<Marker>
  <MarkerIcon>
    <Search />
  </MarkerIcon>
  <MarkerContent>Explored 4 files</MarkerContent>
</Marker>
```

A marker is the quiet line between messages: "Switched branch", "Today",
"Thinking...". It pairs well with [Bubble](/docs/ui/bubble) in a chat thread.

## Variants [#variants]

`default` is an inline note. `separator` centers a label between two lines.
`border` adds a line under the row.

```tsx
<Marker variant="separator">
  <MarkerContent>Yesterday</MarkerContent>
</Marker>
```

Keep separator labels short. The lines only get the space the label leaves.

## Tones [#tones]

Set `tone` when the note carries good or bad news. Colors match `Alert` and
`Badge`, mixed toward the foreground to stay readable in both themes.

```tsx
<Marker tone="success">
  <MarkerIcon>
    <CircleCheck />
  </MarkerIcon>
  <MarkerContent>Build passed</MarkerContent>
</Marker>
```

Color is a bonus, not the message. Pair it with an icon or words.

## Stacked icon [#stacked-icon]

`MarkerIcon` sizes any icon to the text. Add `flex-col` to put it above the
text.

```tsx
<Marker className="flex-col">...</Marker>
```

## Status and shimmer [#status-and-shimmer]

For work in progress, set `role="status"`, put a `Spinner` in the icon slot and
add the `shimmer` utility to the text. See the last line of the preview.

```tsx
<Marker role="status">
  <MarkerIcon>
    <Spinner />
  </MarkerIcon>
  <MarkerContent className="shimmer">Thinking...</MarkerContent>
</Marker>
```

## Links and buttons [#links-and-buttons]

Pass `render` to turn the marker into a link or a button. Links get an
underline for free.

```tsx
<Marker render={<a href="/admin/plugins" />}>
  <MarkerContent>View installed plugins</MarkerContent>
</Marker>

<Marker
  render={<button className="hover:text-foreground" onClick={revert} type="button" />}
>
  <MarkerContent>Revert this change</MarkerContent>
</Marker>
```

## Accessibility [#accessibility]

- A marker is a plain `div`. Add `role="status"` for live progress, `render` an
  `a` or `button` when it's clickable, and nothing for a plain note.
- Don't add `role="separator"` to a labeled separator. It would hide the label
  from assistive tech. The lines are decorative pseudo-elements.
- `MarkerIcon` is `aria-hidden`. Give an icon-only marker an `aria-label`.
- Wrap a thread in `role="log"` so new messages and markers are announced in
  order.

## Props [#props]

### Marker [#marker]

<TypeTable
  type={{
    variant: {
      description: 'How the marker sits between content.',
      type: 'default | separator | border',
      default: 'default',
    },
    tone: {
      description: 'Text color, shared with Alert and Badge.',
      type: 'neutral | info | success | warning | destructive',
      default: 'neutral',
    },
    render: {
      description: 'Replaces the root element, such as an `a` or `button`.',
      type: 'ReactElement | ((props, state) => ReactElement)',
    },
    role: {
      description: 'Use `status` for live progress.',
      type: 'AriaRole',
    },
  }}
/>

### MarkerIcon and MarkerContent [#markericon-and-markercontent]

Both render a `span` and take every `span` prop.

## API Reference [#api-reference]

[Base UI - useRender](https://base-ui.com/react/utils/use-render)

# Menubar (/docs/ui/menubar)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Menubar,
  MenubarContent,
  MenubarItem,
  MenubarMenu,
  MenubarSeparator,
  MenubarShortcut,
  MenubarTrigger,
} from '@vitnode/core/components/ui/menubar'
```

```tsx
<Menubar>
  <MenubarMenu>
    <MenubarTrigger>File</MenubarTrigger>
    <MenubarContent className="w-56">
      <MenubarItem>
        New tab
        <MenubarShortcut>⌘T</MenubarShortcut>
      </MenubarItem>
      <MenubarItem>New window</MenubarItem>
      <MenubarSeparator />
      <MenubarItem>Print...</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
  <MenubarMenu>
    <MenubarTrigger>Edit</MenubarTrigger>
    <MenubarContent className="w-56">
      <MenubarItem>Undo</MenubarItem>
      <MenubarItem>Redo</MenubarItem>
    </MenubarContent>
  </MenubarMenu>
</Menubar>
```

Each `MenubarMenu` is a trigger plus its content. Open one, then hover the next
trigger: it opens straight away, like a desktop menu bar.

## Submenus [#submenus]

Nest a `MenubarSub` to tuck actions one level deeper. It opens on hover, click
or the right arrow.

```tsx
<MenubarSub>
  <MenubarSubTrigger>Share</MenubarSubTrigger>
  <MenubarSubContent className="w-44">
    <MenubarItem>Email link</MenubarItem>
  </MenubarSubContent>
</MenubarSub>
```

## Checkbox and radio items [#checkbox-and-radio-items]

Open **View** and **Profiles** above. `MenubarCheckboxItem` toggles on its own,
items in a `MenubarRadioGroup` pick one. Both work controlled or uncontrolled.

```tsx
<MenubarCheckboxItem checked={showBookmarks} onCheckedChange={setShowBookmarks}>
  Always show bookmarks bar
</MenubarCheckboxItem>
<MenubarRadioGroup onValueChange={setProfile} value={profile}>
  <MenubarRadioItem value="andy">Andy</MenubarRadioItem>
</MenubarRadioGroup>
```

The check mark sits at the start of the row, like in the
[Dropdown Menu](/docs/ui/dropdown-menu). Add `inset` to plain items, labels and
sub-triggers in the same menu so their text lines up.

## Shortcuts and destructive items [#shortcuts-and-destructive-items]

`MenubarShortcut` is only a label: bind the keys yourself. Use
`variant="destructive"` for actions you can't take back.

```tsx
<MenubarItem>
  Undo
  <MenubarShortcut>⌘Z</MenubarShortcut>
</MenubarItem>
<MenubarItem variant="destructive">Close all windows</MenubarItem>
```

## Accessibility [#accessibility]

- The bar is one tab stop. Left and right arrows move between menus, and move
  the open menu with you.
- Inside a menu, up and down move between items, right opens a submenu, a
  letter jumps to a match and <kbd>Escape</kbd> returns focus to the trigger.
- Triggers and rows grow to a 44px tap target on touch screens.
- Switching between open menus is instant. Reduced motion turns the scale-in
  off.
- A menu bar is a desktop pattern. On small screens keep it short, or offer the
  same actions in a [Dropdown Menu](/docs/ui/dropdown-menu).

## Props [#props]

### Menubar [#menubar]

### MenubarContent [#menubarcontent]

### MenubarItem [#menubaritem]

`MenubarCheckboxItem` takes `checked`, `defaultChecked` and `onCheckedChange`.
`MenubarRadioGroup` takes `value`, `defaultValue` and `onValueChange`. Both item
types accept `inset` and `disabled`. `MenubarMenu` takes `open`, `defaultOpen`
and `onOpenChange` to drive one menu yourself.

## API Reference [#api-reference]

[Base UI - Menubar](https://base-ui.com/react/components/menubar#api-reference)

# Message (/docs/ui/message)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Message,
  MessageAvatar,
  MessageContent,
  MessageFooter,
  MessageGroup,
  MessageHeader,
} from '@vitnode/core/components/ui/message'
```

```tsx
<Message>
  <MessageAvatar>
    <Avatar>
      <AvatarImage alt="VitNode assistant" src="/logo_vitnode_icon.svg" />
      <AvatarFallback>VN</AvatarFallback>
    </Avatar>
  </MessageAvatar>
  <MessageContent>
    <Bubble variant="muted">
      <BubbleContent>How can I help you today?</BubbleContent>
    </Bubble>
  </MessageContent>
</Message>
```

`Message` owns the row: who's talking, which side, and what sits above or
below. The speech bubble is a [Bubble](/docs/ui/bubble).

```text
MessageGroup
└── Message
    ├── MessageAvatar
    └── MessageContent
        ├── MessageHeader
        ├── Bubble / Attachment
        └── MessageFooter
```

## Alignment [#alignment]

`align="end"` marks messages the current user sent. The avatar swaps sides,
and every bubble, attachment, header and footer inside follows, so you don't
set `align` on each `Bubble`. Sides flip on their own in right-to-left
languages.

```tsx
<Message align="end">
  <MessageContent>
    <Bubble>
      <BubbleContent>Sent by me, obviously.</BubbleContent>
    </Bubble>
  </MessageContent>
</Message>
```

## Avatar [#avatar]

`MessageAvatar` sits at the bottom, next to the last bubble. With a
`MessageFooter`, it lifts to line up with the bubble instead.

## Group [#group]

`MessageGroup` tightens the spacing between messages from one sender. Give the
earlier ones an empty `MessageAvatar` so their bubbles line up.

```tsx
<MessageGroup>
  <Message>
    <MessageAvatar />
    <MessageContent>...</MessageContent>
  </Message>
  <Message>
    <MessageAvatar>
      <Avatar>
        <AvatarFallback>AV</AvatarFallback>
      </Avatar>
    </MessageAvatar>
    <MessageContent>...</MessageContent>
  </Message>
</MessageGroup>
```

For several bubbles in one message, use
[`BubbleGroup`](/docs/ui/bubble#grouping) inside `MessageContent`.

## Header, footer and actions [#header-footer-and-actions]

`MessageHeader` holds the sender name and time. `MessageFooter` holds read
receipts or actions like copy and retry.

```tsx
<MessageContent>
  <MessageHeader className="gap-1.5">
    <span className="text-foreground">Ava</span>
    <time dateTime="2026-10-02T09:41">9:41 AM</time>
  </MessageHeader>
  <Bubble variant="muted">
    <BubbleContent>Did the plugin build pass?</BubbleContent>
  </Bubble>
  <MessageFooter>
    <Button aria-label="Copy message" size="icon-xs" variant="ghost">
      <CopyIcon />
    </Button>
  </MessageFooter>
</MessageContent>
```

## Attachments [#attachments]

Drop an [Attachment](/docs/ui/attachment) next to the bubble in
`MessageContent`. It follows the message's alignment.

## Accessibility [#accessibility]

- `Message` has no role. Put `role="log"` and an `aria-label` on the
  conversation container.
- Alignment only helps sighted users. Name the sender in text too, with a
  `MessageHeader` (`className="sr-only"` for your own messages).
- Wrap timestamps in `<time dateTime="...">`.
- Give `AvatarImage` the sender's name as `alt`. If a header already names
  them, set `aria-hidden="true"` on `MessageAvatar`.
- Icon-only footer actions need an `aria-label`.
- For "someone is typing", use a [Marker](/docs/ui/marker) with
  `role="status"`.

## Props [#props]

### Message [#message]

The other parts accept every `div` prop, including `className`.

## API Reference [#api-reference]

[shadcn/ui - Message](https://ui.shadcn.com/docs/components/base/message)

# Motion (/docs/ui/motion)

Motion in VitNode answers one question: _where did that come from, and where
did it go?_ Everything reacts on press, moves along a real path and can change
its mind halfway. Nothing bounces for fun.

## Respond on press [#respond-on-press]

A press shows up in under 150ms, or it feels broken. `Button` dips to
`active:scale-97`; tiny targets like `Checkbox` go further, to `scale-90`, so
the dip is still visible under a thumb.

## Easing [#easing]

`ease-fluid` starts at full speed and spends its time settling, so the UI looks
like it moved the instant you asked. `ease-in` waits before reacting, which
feels like lag. `linear` is for progress bars and spinners only.

```css
--ease-fluid: cubic-bezier(0.22, 1, 0.36, 1);
```

## Timing [#timing]

| What                           | Enter   | Exit    |
| ------------------------------ | ------- | ------- |
| Tooltip, popover, menu         | 150ms   | 100ms   |
| Dialog, alert dialog           | 200ms   | 150ms   |
| Sheet, drawer, big panels      | 300ms   | 200ms   |
| Press feedback, hover, toggles | ≤ 150ms | ≤ 150ms |

Exits are shorter than entrances: once you're done with something, it should
get out of the way.

## Interruptible [#interruptible]

A transition always starts from wherever the element is right now, so it can
reverse mid-flight. A keyframe animation restarts from frame one. VitNode
overlays use transitions keyed on Base UI's `data-starting-style` and
`data-ending-style` instead of `@keyframes`.

```tsx
<div className="ease-fluid transition-[opacity,scale] duration-150 data-starting-style:scale-95 data-starting-style:opacity-0 data-ending-style:scale-95 data-ending-style:opacity-0 data-ending-style:duration-100 motion-reduce:transition-none" />
```

## Springs [#springs]

When a component needs a spring (`Switch`, `ToggleGroup`, `Combobox` chips), it
uses `motion/react` with a critically damped spring: fast, no wobble. Save
`bounce` for when a gesture carried momentum into the release, like flinging a
drawer away.

```tsx
const SPRING = { type: 'spring', duration: 0.3, bounce: 0 } as const

<m.span layout transition={shouldReduceMotion ? { duration: 0 } : SPRING} />
```

## Grow from the trigger [#grow-from-the-trigger]

Popovers, menus and tooltips scale out of their trigger with
`origin-(--transform-origin)`, which Base UI sets from the side and alignment.
Leave and return along the same path: a sheet slides back to the edge it came
from.

## Reduced motion [#reduced-motion]

With reduced motion on, slides become crossfades and springs run with
`duration: 0`. Fading is fine, travel isn't. CSS gets `motion-reduce:`, motion
code reads `useReducedMotion()`, and frosted surfaces drop their blur with
`reduced-transparency:`.

```tsx
<div className="bg-background/80 backdrop-blur-md motion-reduce:transition-none reduced-transparency:bg-background reduced-transparency:backdrop-blur-none" />
```

## Related [#related]

# Nullable Number (/docs/ui/nullable-number)

## Preview [#preview]

A [Number Field](/docs/ui/number-field) plus one checkbox, for when the honest
answer is "no limit".

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormNullableNumber } from '@vitnode/core/components/form/fields/nullable-number'
```

```tsx
const formSchema = z.object({
  max_members: z.number().int().min(1).nullable().default(10),
})

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'max_members',
      component: props => (
        <AutoFormNullableNumber
          {...props}
          label="Maximum members"
          min={1}
          toggleLabel="Unlimited"
        />
      ),
    },
  ]}
/>
```

## Value [#value]

The value is `number | null`. Checking the box stores `null` and disables the
input. Unchecking it restores the last number. Clearing the input stores `0`.

Back it with `z.number().nullable()`. If the field can be
[hidden](/docs/ui/auto-form#conditional-fields), add a `default` so it never
blocks submission.

## Labels [#labels]

The second field in the preview uses all three labels:

```tsx
<AutoFormNullableNumber
  {...props}
  label="Auto-logout"
  orLabel="or"
  toggleLabel="Never"
  unitLabel="minutes"
/>
```

Every other prop (`min`, `max`, `step`, `format`, `placeholder`…) goes to the
[Number Field](/docs/ui/number-field#props). Pass `min`/`max` here and in the
schema: the schema validates, the props clamp the buttons and keys.

## Props [#props]

# Number Field (/docs/ui/number-field)

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormNumber } from '@vitnode/core/components/form/fields/number'
```

```tsx
const formSchema = z.object({
  guests: z.number().int().min(1).max(12).default(2),
})

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'guests',
      component: props => (
        <AutoFormNumber {...props} label="Guests" max={12} min={1} unitLabel="people" />
      ),
    },
  ]}
/>
```

The form stores a real `number`, or `null` when cleared. Pass `min`/`max` to
both: the schema validates, the props clamp.

Need an "unlimited" checkbox? Use [Nullable Number](/docs/ui/nullable-number).

</Tab>

```ts
import {
  NumberField,
  NumberFieldDecrement,
  NumberFieldGroup,
  NumberFieldIncrement,
  NumberFieldInput,
} from '@vitnode/core/components/ui/number-field'
```

```tsx
const [value, setValue] = React.useState<number | null>(2)

<NumberField max={8} min={0} onValueChange={setValue} value={value}>
  <NumberFieldGroup>
    <NumberFieldDecrement />
    <NumberFieldInput aria-label="Coffees per day" />
    <NumberFieldIncrement />
  </NumberFieldGroup>
</NumberField>
```

Uncontrolled? Use `defaultValue` with `onValueCommitted`, which fires on blur
or button release instead of every keystroke.

</Tab>
</Tabs>

## Min, max and step [#min-max-and-step]

`min`/`max` disable the button at a limit and clamp typed values on blur.
`step` is one press, `largeStep` adds <kbd>Shift</kbd>, `smallStep` adds

<kbd>Alt</kbd>. `snapOnStep` snaps to the nearest multiple.

```tsx
<NumberField largeStep={50} max={500} min={0} snapOnStep step={5}>
  …
</NumberField>
```

## Formatting [#formatting]

`format` takes [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options).
The value stays a number: `0.15` shows as `15%`. Formatting follows the app
locale unless you pass `locale`.

```tsx
<NumberField
  defaultValue={19.99}
  format={{ style: 'currency', currency: 'USD' }}
>
  …
</NumberField>
```

## Scrub area [#scrub-area]

Drag the label in the [preview](#preview) sideways. `NumberFieldScrubArea`
makes a label scrubbable. Pass the field's `id` as `htmlFor` so a click still
focuses the input.

```tsx
const id = React.useId()

<NumberField id={id} max={8} min={0}>
  <NumberFieldScrubArea htmlFor={id} label="Coffees per day" />
  <NumberFieldGroup>…</NumberFieldGroup>
</NumberField>
```

`allowWheelScrub` adds mouse-wheel changes while focused.

## Sizes [#sizes]

```tsx
<NumberField size="sm">…</NumberField>
```

## Disabled and read-only [#disabled-and-read-only]

`readOnly` stays focusable, unlike `disabled`.

## Accessibility [#accessibility]

- The input is a text field with `inputMode`, so `$19.99` fits and phones
  show a number pad.
- <kbd>↑</kbd> / <kbd>↓</kbd> step, <kbd>Home</kbd> / <kbd>End</kbd> jump to
  `min` / `max` when set.
- The buttons are labelled "Increase" / "Decrease", skip <kbd>Tab</kbd>, and
  grow to a 44px hit area on touch.
- Name the input with a label (`htmlFor` + `id`), a scrub area or `aria-label`.
  `AutoFormNumber` does it for you.

## Props [#props]

<TypeTable
  type={{
    value: {
      description: 'The number (controlled). `null` means empty.',
      type: 'number | null',
    },
    defaultValue: {
      description: 'The starting number when uncontrolled.',
      type: 'number',
    },
    onValueChange: {
      description: 'Every change: typing, buttons, keys, scrubbing.',
      type: '(value: number | null) => void',
    },
    onValueCommitted: {
      description: 'Final change only: blur, or button/scrub release.',
      type: '(value: number | null) => void',
    },
    min: { description: 'Lowest allowed value.', type: 'number' },
    max: { description: 'Highest allowed value.', type: 'number' },
    step: {
      description: 'Amount per click or arrow press.',
      type: 'number | "any"',
      default: '1',
    },
    largeStep: {
      description: 'Amount with Shift held.',
      type: 'number',
      default: '10',
    },
    smallStep: {
      description: 'Amount with Alt held.',
      type: 'number',
      default: '0.1',
    },
    snapOnStep: {
      description: 'Snap to the nearest step multiple.',
      type: 'boolean',
      default: 'false',
    },
    format: {
      description: 'How the value is displayed.',
      type: 'Intl.NumberFormatOptions',
    },
    locale: {
      description: 'Locale for formatting and parsing.',
      type: 'Intl.LocalesArgument',
      default: 'the app locale',
    },
    size: {
      description: 'Height of the field.',
      type: '"sm" | "default" | "lg"',
      default: '"default"',
    },
    allowWheelScrub: {
      description: 'Mouse wheel changes the value while focused.',
      type: 'boolean',
      default: 'false',
    },
    disabled: {
      description: 'Ignores every interaction.',
      type: 'boolean',
      default: 'false',
    },
    readOnly: {
      description: 'Shows the value but blocks changes.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

`AutoFormNumber` takes all of these except `value`, `defaultValue` and
`onValueChange` (the form owns them), plus `label`, `description`,
`placeholder` and `unitLabel`.

## API Reference [#api-reference]

[Base UI - Number Field](https://base-ui.com/react/components/number-field)

# Page Title (/docs/ui/page-title)

## Preview [#preview]

## Usage [#usage]

```ts
import { PageTitle } from '@vitnode/core/components/ui/page-title'
```

```tsx
<PageTitle desc="Group users and decide what each group can do." h1="Roles">
  <Button>
    <PlusIcon />
    Create role
  </Button>
</PageTitle>
```

`children` become actions on the right. On phones everything stacks and the
actions go full width. From `sm` up, heading left, actions right.

## h1 or h2 [#h1-or-h2]

Pass exactly one of `h1` or `h2`. TypeScript complains about both or neither.

- `h1` is the page heading (`text-2xl sm:text-3xl`). One per page.
- `h2` is a section inside a page that already has an `h1`, like a settings
  panel (`text-xl sm:text-2xl`).

```tsx
<PageTitle h2="Danger zone" />
```

The previews use `h2`, since this page already has an `h1`.

## Subtitle [#subtitle]

A small muted line above the heading. Use it for where the page lives.

```tsx
<PageTitle
  desc="Sign in faster with accounts you already have."
  h1="Connected accounts"
  subtitle="Settings"
/>
```

## Back link [#back-link]

`back` adds an arrow link above the heading (and above `subtitle`). Good for
edit and detail pages under a list. It's a TanStack Router `Link`, so it
navigates client-side and preloads. The actions side stays free.

```tsx
<PageTitle
  back={{ href: '/admin/core/users', label: 'Back to users' }}
  desc="Edit the details shown on the public profile."
  h1="Edit user"
>
  <Button>Save changes</Button>
</PageTitle>
```

## Multiple actions [#multiple-actions]

Pass as many `children` as you need; they wrap on small screens. Keep one
primary button and make the rest `outline` or `ghost`.

```tsx
<PageTitle
  desc="Everything published on the site, newest first."
  h1="Blog posts"
>
  <Button variant="outline">
    <DownloadIcon />
    Export
  </Button>
  <Button>
    <PlusIcon />
    New post
  </Button>
</PageTitle>
```

## Spacing [#spacing]

`PageTitle` has a built-in `mb-6`. Drop it when the parent already uses `gap-*`:

```tsx
<div className="flex flex-col gap-4">
  <PageTitle className="mb-0" h1="Devices" />
  <DevicesList />
</div>
```

## Accessibility [#accessibility]

- The heading is a real `h1` or `h2`, so it appears in heading navigation.
- `subtitle` is a `p`, not a heading, so it stays out of the outline.
- Give icon-only actions an `aria-label` or `sr-only` text.

## Props [#props]

# Pagination (/docs/ui/pagination)

## Preview [#preview]

<Callout title="Building a table?">
  [Data Table](/docs/ui/data-table) already paginates, URL state included. Use
  `Pagination` for your own lists, feeds and galleries.
</Callout>

## Usage [#usage]

```ts
import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from '@vitnode/core/components/ui/pagination'
```

```tsx
<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="?page=1" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=1">1</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2" isActive>
        2
      </PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="?page=3" />
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

Every link is a real `<a>`, so pages stay crawlable and middle-click opens a new
tab. Below `sm`, previous and next shrink to a chevron that flips in RTL.

## With router links [#with-router-links]

Keep the `href` for crawlers, and let TanStack Router handle the click:

```tsx
const navigate = useNavigate()

const goTo = (page: number) => (event: React.MouseEvent<HTMLAnchorElement>) => {
  event.preventDefault()
  void navigate({ to: '.', search: (prev) => ({ ...prev, page }) })
}

;<PaginationLink
  href={`?page=${page}`}
  isActive={page === current}
  onClick={goTo(page)}
>
  {page}
</PaginationLink>
```

## Ellipsis [#ellipsis]

Show the first page, the last page and the current one. `PaginationEllipsis`
covers the rest. This helper keeps five slots, so the row never jumps:

```tsx
type PageSlot = 'ellipsis-end' | 'ellipsis-start' | number

const range = (from: number, to: number) =>
  Array.from({ length: to - from + 1 }, (_, step) => from + step)

const pageWindow = (current: number, total: number): PageSlot[] => {
  if (total <= 5) return range(1, total)
  if (current <= 3) return [1, 2, 3, 'ellipsis-end', total]
  if (current >= total - 2) {
    return [1, 'ellipsis-start', ...range(total - 2, total)]
  }

return [1, 'ellipsis-start', current, 'ellipsis-end', total]
}
```

```tsx
{
  pageWindow(page, total).map((slot) => (
    <PaginationItem key={slot}>
      {typeof slot === 'number' ? (
        <PaginationLink href={`?page=${slot}`} isActive={slot === page}>
          {slot}
        </PaginationLink>
      ) : (
        <PaginationEllipsis />
      )}
    </PaginationItem>
  ))
}
```

## Small screens [#small-screens]

Shrink the preview to phone width: the numbers give way to "Page 2 of 12". Add
`hidden sm:block` to each number's item, plus one item for the phone line:

```tsx
<PaginationItem className="sm:hidden">
  <span className="text-muted-foreground px-2 text-sm">
    Page {page} of {total}
  </span>
</PaginationItem>
```

## Disabled ends [#disabled-ends]

There is no page zero (we checked). Drop the `href` so the keyboard skips the
link, and add `role="link"` with `aria-disabled` so screen readers hear it as
unavailable:

```tsx
<PaginationPrevious
  {...(page > 1
    ? { href: `?page=${page - 1}` }
    : {
        'aria-disabled': true,
        className: 'pointer-events-none',
        role: 'link',
      })}
/>
```

## Custom labels [#custom-labels]

`text` replaces the translated "Previous" / "Next". Pass a matching
`aria-label` too, or screen readers still announce "Previous page".

```tsx
<PaginationNext aria-label="Older posts" href="?page=3" text="Older posts" />
```

## Accessibility [#accessibility]

- `Pagination` is a `nav` landmark with a translated "Pagination" label.
- The active link gets `aria-current="page"`.
- Previous and next keep their translated label when only the chevron shows.
- `PaginationEllipsis` hides its icon and reads "More pages" to screen readers.
- Announce page changes that don't reload, for example with an
  `aria-live="polite"` line like the preview's "1-3 of 36".

## Props [#props]

### PaginationLink [#paginationlink]

### PaginationPrevious / PaginationNext [#paginationprevious--paginationnext]

Every `PaginationLink` prop, plus:

## API Reference [#api-reference]

[shadcn/ui - Pagination](https://ui.shadcn.com/docs/components/base/pagination)

# Popover (/docs/ui/popover)

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverHeader,
  PopoverTitle,
  PopoverTrigger,
} from '@vitnode/core/components/ui/popover'
```

```tsx
<Popover>
  <PopoverTrigger render={<Button variant="outline">Invite</Button>} />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Invite friends</PopoverTitle>
      <PopoverDescription>The link works for 7 days.</PopoverDescription>
    </PopoverHeader>
  </PopoverContent>
</Popover>
```

`PopoverContent` is `w-72` with a `gap-4` column, so stacked children space
themselves. Override the width with `className`.

## With a form [#with-a-form]

Drop an `AutoForm` in for quick edits. Control `open` so you can close it after
a successful submit.

```tsx
const [open, setOpen] = React.useState(false)

<Popover onOpenChange={setOpen} open={open}>
  <PopoverTrigger render={<Button variant="outline">Add link</Button>} />
  <PopoverContent align="start" className="w-80">
    <AutoForm
      fields={fields}
      formSchema={formSchema}
      onSubmit={values => {
        insertLink(values)
        setOpen(false)
      }}
    />
  </PopoverContent>
</Popover>
```

Longer forms belong in a [Dialog](/docs/ui/dialog), which also guards unsaved
changes.

## Position [#position]

Set `side` and `align` on `PopoverContent`. It flips when there's no room and
grows out of the trigger.

## Props [#props]

## API Reference [#api-reference]

[Base UI - Popover](https://base-ui.com/react/components/popover#api-reference)

# Progress (/docs/ui/progress)

## Usage [#usage]

```ts
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from '@vitnode/core/components/ui/progress'
```

```tsx
<Progress value={42}>
  <ProgressLabel>Uploading photos</ProgressLabel>
  <ProgressValue />
</Progress>
```

`ProgressLabel` names the bar for screen readers. `ProgressValue` uses tabular
numbers, so digits don't wiggle as they count.

The bar grows with a `scaleX` transform, so frequent updates stay smooth. With
reduced motion it jumps straight to the new value.

## Indeterminate [#indeterminate]

Don't know how long it takes? Pass `value={null}`. A segment sweeps across in
the reading direction. With reduced motion the track shows a static tint
instead.

```tsx
<Progress value={null}>
  <ProgressLabel>Preparing export</ProgressLabel>
</Progress>
```

## Custom range and format [#custom-range-and-format]

Set `min` and `max` for any range. `format` takes `Intl.NumberFormat` options,
and `ProgressValue` takes a function for full control. Use
`getAriaValueText` when the spoken value needs more context.

```tsx
<Progress max={10} value={7}>
  <ProgressLabel>Onboarding steps</ProgressLabel>
  <ProgressValue>{(_, value) => `${value} of 10`}</ProgressValue>
</Progress>
```

## Props [#props]

### Progress [#progress]

<TypeTable
  type={{
    value: {
      description: 'Current value. `null` makes the bar indeterminate.',
      type: 'number | null',
      required: true,
    },
    min: {
      description: 'Lowest value.',
      type: 'number',
      default: '0',
    },
    max: {
      description: 'Highest value.',
      type: 'number',
      default: '100',
    },
    format: {
      description: 'Number format for the value.',
      type: 'Intl.NumberFormatOptions',
    },
    locale: {
      description: 'Locale for the number format.',
      type: 'Intl.LocalesArgument',
    },
    getAriaValueText: {
      description: 'Builds the text screen readers announce.',
      type: '(formattedValue, value) => string',
    },
  }}
/>

### ProgressValue [#progressvalue]

<TypeTable
  type={{
    children: {
      description: 'Renders the value yourself.',
      type: '(formattedValue, value) => ReactNode',
    },
  }}
/>

## API Reference [#api-reference]

[Base UI - Progress](https://base-ui.com/react/components/progress#api-reference)

# Radio Group (/docs/ui/radio-group)

## Preview [#preview]

## Usage [#usage]

```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormRadioGroup } from '@vitnode/core/components/form/fields/radio-group'
import { z } from 'zod'

const formSchema = z.object({
  sort: z.enum(['latest', 'top', 'unanswered']).default('latest'),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'sort',
      component: (props) => (
        <AutoFormRadioGroup
          {...props}
          label="Default sort"
          labels={[
            {
              value: 'latest',
              label: 'Latest activity',
              description: 'New replies float up.',
            },
            { value: 'top', label: 'Most liked' },
            { value: 'unanswered', label: 'Unanswered first', disabled: true },
          ]}
        />
      ),
    },
  ]}
/>
```

Options come from the `z.enum()`. `labels` only adds text: an enum value
without a label shows the raw value.

</Tab>
  <Tab value="Manual">

```tsx
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldLabel,
} from '@vitnode/core/components/ui/field'
import {
  RadioGroup,
  RadioGroupItem,
} from '@vitnode/core/components/ui/radio-group'
```

```tsx
<RadioGroup aria-label="Default sort" defaultValue="latest">
  <Field orientation="horizontal">
    <RadioGroupItem id="latest" value="latest" />
    <FieldContent>
      <FieldLabel htmlFor="latest">Latest activity</FieldLabel>
      <FieldDescription>New replies float up.</FieldDescription>
    </FieldContent>
  </Field>
  <Field data-disabled orientation="horizontal">
    <RadioGroupItem disabled id="unanswered" value="unanswered" />
    <FieldLabel htmlFor="unanswered">Unanswered first</FieldLabel>
  </Field>
</RadioGroup>
```

</Tab>
</Tabs>

Arrow keys move between options and select them. Tab leaves the group.

## Blocks [#blocks]

`variant="blocks"` turns each option into a clickable card. It's built from
[Field choice cards](/docs/ui/field#choice-cards).

```tsx
<AutoFormRadioGroup
  {...props}
  label="Registration"
  labels={labels}
  variant="blocks"
/>
```

## Props [#props]

`AutoFormRadioGroup` also accepts every
[Base UI Radio Group](https://base-ui.com/react/components/radio#api-reference)
prop.

## API Reference [#api-reference]

[Base UI - Radio Group](https://base-ui.com/react/components/radio#api-reference)

# Resizable (/docs/ui/resizable)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from '@vitnode/core/components/ui/resizable'
```

```tsx
<div className="h-80">
  <ResizablePanelGroup className="rounded-lg border">
    <ResizablePanel defaultSize="35%">Sidebar</ResizablePanel>
    <ResizableHandle />
    <ResizablePanel>Content</ResizablePanel>
  </ResizablePanelGroup>
</div>
```

The group sets an inline `height: 100%`, so a height class on it is ignored.
Give the **parent** a height instead.

Groups nest: put a `ResizablePanelGroup` inside a `ResizablePanel` to split it
again, like the terminal in the preview.

## Vertical [#vertical]

```tsx
<ResizablePanelGroup orientation="vertical">
```

## With handle [#with-handle]

`withHandle` adds a grip, so people know the divider can be grabbed.

```tsx
<ResizableHandle withHandle />
```

## Sizes [#sizes]

The value's type decides the unit:

- a **string** without a unit is a percentage: `"30"` equals `"30%"`;
- a **number** is pixels: `minSize={180}` is 180px, not 180%;
- other CSS units work too: `"12rem"`, `"20vw"`.

```tsx
<ResizablePanel defaultSize="25%" maxSize="40%" minSize={180}>
```

Panels without `defaultSize` share the leftover space. Double-click a handle to
reset its panel to `defaultSize`.

## Collapsible [#collapsible]

A `collapsible` panel snaps to `collapsedSize` once dragged below `minSize`.
For a toggle button, call `collapse()` or `expand()` on its `panelRef`.

```tsx
<ResizablePanel collapsedSize="8%" collapsible defaultSize="35%" minSize="25%">
```

## Persisting the layout [#persisting-the-layout]

`defaultLayout` takes a map of panel `id` to percentage. `onLayoutChanged`
fires after every finished resize. Wire both to storage, and give each panel a
stable `id`.

```tsx
const storageKey = 'my-layout'

const readLayout = () => {
  try {
    return localStorage.getItem(storageKey)
  } catch {
    return null
  }
}

export const RememberedLayout = () => {
  const stored = React.useSyncExternalStore(
    () => () => {},
    readLayout,
    () => null,
  )

return (
    <ResizablePanelGroup
      defaultLayout={stored ? JSON.parse(stored) : undefined}
      onLayoutChanged={(layout, meta) => {
        if (!meta.isUserInteraction) return

localStorage.setItem(
          storageKey,
          JSON.stringify(meta.requestedLayout ?? layout),
        )
      }}
    >
      <ResizablePanel defaultSize="40%" id="sidebar">
        Sidebar
      </ResizablePanel>
      <ResizableHandle withHandle />
      <ResizablePanel id="content">Content</ResizablePanel>
    </ResizablePanelGroup>
  )
}
```

The `null` server snapshot keeps SSR happy: the server renders default sizes,
then the browser swaps in the saved ones. Save `meta.requestedLayout` when it
exists. It's what the user asked for, before a small screen squeezed it.

## Accessibility [#accessibility]

- Each handle is a focusable `role="separator"` with `aria-valuenow`,
  `aria-valuemin`, `aria-valuemax` and `aria-controls`.
- Arrow keys resize by 5% along the group's orientation.
- `Home` and `End` jump to the minimum or maximum size.
- `Enter` collapses or expands a `collapsible` panel.
- `F6` moves to the next handle, `Shift + F6` to the previous one.
- Touch dragging only claims the resize axis, so panels still scroll the other
  way.

## Props [#props]

### ResizablePanelGroup [#resizablepanelgroup]

<TypeTable
  type={{
    orientation: {
      description: 'Direction panels are laid out and resized in.',
      type: '"horizontal" | "vertical"',
      default: '"horizontal"',
    },
    defaultLayout: {
      description: 'Initial layout as panel id → percentage (0-100).',
      type: 'Record<string, number>',
    },
    onLayoutChange: {
      description: 'Fires on every change, including each drag move.',
      type: '(layout: Layout) => void',
    },
    onLayoutChanged: {
      description: 'Fires once a resize finishes. The place to save a layout.',
      type: '(layout: Layout, meta: { isUserInteraction: boolean; requestedLayout?: Layout }) => void',
    },
    disabled: {
      description: 'Turns resizing off for the whole group.',
      type: 'boolean',
      default: 'false',
    },
    groupRef: {
      description: 'Imperative API: `getLayout()`, `setLayout(layout)`.',
      type: 'Ref<GroupImperativeHandle>',
    },
    id: {
      description: 'Unique group id. Falls back to `useId`.',
      type: 'string | number',
    },
  }}
/>

### ResizablePanel [#resizablepanel]

<TypeTable
  type={{
    id: {
      description: 'Unique id inside the group. Required to persist a layout.',
      type: 'string | number',
    },
    defaultSize: {
      description: 'Initial size. Strings are percentages, numbers are pixels.',
      type: 'string | number',
    },
    minSize: {
      description: 'Smallest allowed size.',
      type: 'string | number',
      default: '"0%"',
    },
    maxSize: {
      description: 'Largest allowed size.',
      type: 'string | number',
      default: '"100%"',
    },
    collapsible: {
      description: 'Collapses when dragged below `minSize`.',
      type: 'boolean',
      default: 'false',
    },
    collapsedSize: {
      description: 'Size when collapsed.',
      type: 'string | number',
      default: '"0%"',
    },
    disabled: {
      description: 'Cannot be resized, directly or by a neighbour.',
      type: 'boolean',
      default: 'false',
    },
    onResize: {
      description: 'Fires with the new size on every resize.',
      type: '(size: { asPercentage: number; inPixels: number }) => void',
    },
    panelRef: {
      description:
        'Imperative API: `collapse()`, `expand()`, `getSize()`, `isCollapsed()`, `resize(size)`.',
      type: 'Ref<PanelImperativeHandle>',
    },
  }}
/>

### ResizableHandle [#resizablehandle]

## API Reference [#api-reference]

[react-resizable-panels](https://react-resizable-panels.vercel.app/)

# Roles (/docs/ui/roles)

## Preview [#preview]

Each role shows a color dot (when it has a color) and its name.

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormRoles } from '@vitnode/core/components/form/fields/input-roles'
import { searchAdminRolesInBrowser } from '@vitnode/core/tanstack/admin/roles'
```

`search` is required. In the AdminCP, use `searchAdminRolesInBrowser`: it
reads the roles list (AdminCP session required) and skips the **guest** role.

```tsx
const formSchema = z.object({ roleId: z.number() })

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'roleId',
      component: props => (
        <AutoFormRoles
          {...props}
          label="Primary role"
          placeholder="Select a role"
          search={searchAdminRolesInBrowser}
        />
      ),
    },
  ]}
/>
```

The value is one id. Picking again replaces it.

</Tab>

```tsx
const formSchema = z.object({ roleIds: z.array(z.number()).min(1) })

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'roleIds',
      component: props => (
        <AutoFormRoles
          {...props}
          label="Additional roles"
          multiple
          placeholder="Add a role"
          search={searchAdminRolesInBrowser}
        />
      ),
    },
  ]}
/>
```

The value is an array of ids, shown as removable chips. Picking a chosen role
again removes it.

</Tab>
</Tabs>

## Editing an existing record [#editing-an-existing-record]

Pass the saved roles as `selected`, or the chips show raw ids.

```tsx
<AutoFormRoles {...props} multiple search={search} selected={user.roles} />
```

## Excluding roles [#excluding-roles]

`excludeIds` hides roles another field already owns.

```tsx
<AutoFormRoles
  {...props}
  excludeIds={[primaryRoleId]}
  multiple
  search={search}
/>
```

## Names per language [#names-per-language]

The field shows the active locale's name, then the first translation, then
the id.

```ts
import { roleOptionName } from '@vitnode/core/components/form/fields/input-roles'

roleOptionName(role, 'pl')
```

## Props [#props]

| Prop                | Type                                       | Default            | What it does                                 |
| ------------------- | ------------------------------------------ | ------------------ | -------------------------------------------- |
| `search`            | `(value: string) => Promise<RoleOption[]>` | required           | Looks up roles                               |
| `multiple`          | `boolean`                                  | `false`            | `number[]` instead of `number`, with chips   |
| `label`             | `ReactNode`                                | -                  | Field label                                  |
| `description`       | `ReactNode`                                | -                  | Help text under the control                  |
| `placeholder`       | `string`                                   | `Select an option` | Shown while nothing is chosen                |
| `searchPlaceholder` | `string`                                   | `Search...`        | Placeholder inside the search box            |
| `selected`          | `RoleOption[]`                             | `[]`               | Roles the field already knows                |
| `excludeIds`        | `number[]`                                 | `[]`               | Roles the picker must not offer              |
| `disabled`          | `boolean`                                  | `false`            | Blocks opening the picker and removing chips |

`RoleOption` is `{ id, color, name }`, with `name` as
`{ languageCode, name }[]`.

## See also [#see-also]

- [User](/docs/ui/user) - the same idea for people.
- [Combobox](/docs/ui/combobox) - when the options are strings, not records.

# Scroll Area (/docs/ui/scroll-area)

## Preview [#preview]

## Usage [#usage]

```ts
import { ScrollArea } from '@vitnode/core/components/ui/scroll-area'
```

```tsx
<ScrollArea className="h-72 w-56 rounded-lg border">
  <ul className="flex flex-col divide-y p-4">...</ul>
</ScrollArea>
```

Give it a fixed height. Everything taller than that scrolls.

## Behaviour [#behaviour]

- The scrollbar stays hidden until you scroll or hover, then fades out again.
- The top or bottom edge fades whenever there's more to scroll that way.
- The edge fade drops while the viewport has keyboard focus, so the focus ring
  is never masked.
- It only renders a vertical scrollbar, and the edge fade is vertical too. For
  horizontal rows, use [Scroll Fade](/docs/ui/scroll-fade).

## API Reference [#api-reference]

[Base UI - Scroll Area](https://base-ui.com/react/components/scroll-area#api-reference)

# Scroll Fade (/docs/ui/scroll-fade)

## Preview [#preview]

## Usage [#usage]

Scroll Fade is a Tailwind utility, not a component, so there's nothing to
import. It ships with the `shadcn` package, which VitNode apps already load in
`src/styles.css`:

```css
@import 'shadcn/tailwind.css';
```

Put the class on the element that scrolls:

```tsx
<div className="scroll-fade h-64 overflow-y-auto">...</div>
```

Only edges with hidden content fade. Nothing overflows? Nothing fades, so it's
safe on any list. It uses `mask-image`, so it dissolves the content itself and
works on any background.

| Class              | Fades                                    |
| ------------------ | ---------------------------------------- |
| `scroll-fade`      | Top and bottom (same as `scroll-fade-y`) |
| `scroll-fade-y`    | Top and bottom                           |
| `scroll-fade-x`    | Inline start and end, mirrors in RTL     |
| `scroll-fade-t`    | Top only                                 |
| `scroll-fade-b`    | Bottom only                              |
| `scroll-fade-s`    | Inline start only, mirrors in RTL        |
| `scroll-fade-e`    | Inline end only, mirrors in RTL          |
| `scroll-fade-l`    | Left only, ignores reading direction     |
| `scroll-fade-r`    | Right only, ignores reading direction    |
| `scroll-fade-none` | Nothing, turns the fade off              |

## Vertical [#vertical]

Keep the card's background and border on a wrapper. Put `scroll-fade` on the
inner scroller, so the list fades and the card doesn't:

```tsx
<section className="bg-card rounded-xl border">
  <h3 className="border-b px-4 py-3">Notifications</h3>
  <div
    aria-label="Notifications"
    className="scroll-fade h-64 overflow-y-auto"
    role="region"
    tabIndex={0}
  >
    <ul>...</ul>
  </div>
</section>
```

## Horizontal [#horizontal]

Use `scroll-fade-x` for rows of chips or cards, as in the preview. Add
`no-scrollbar` (same package) when the scrollbar would only fade along:

```tsx
<div className="scroll-fade-x no-scrollbar overflow-x-auto">
  <ul className="flex w-max gap-2">...</ul>
</div>
```

The [Attachment](/docs/ui/attachment) list and the breadcrumb trail use exactly
this.

## One edge only [#one-edge-only]

`scroll-fade-b` suits a chat log that grows downward. `scroll-fade-s` and
`scroll-fade-e` respect RTL in horizontal rows.

```tsx
<div className="scroll-fade-b h-80 overflow-y-auto">...</div>
```

## Fade size [#fade-size]

The default is 12% of the container, capped at `40px`. Use the spacing scale
(`scroll-fade-16`) or any length or percentage:

```tsx
<div className="scroll-fade scroll-fade-[15%] overflow-y-auto" />
```

`scroll-fade-t-*`, `scroll-fade-b-*`, `scroll-fade-s-*` and `scroll-fade-e-*`
size a single edge:

```tsx
<div className="scroll-fade scroll-fade-t-2 scroll-fade-b-8 overflow-y-auto" />
```

The fade eases in over `96px` of scrolling. Change that with
`--scroll-fade-reveal`:

```tsx
<div className="scroll-fade overflow-y-auto [--scroll-fade-reveal:48px]" />
```

## Turning it off [#turning-it-off]

`scroll-fade-none` removes the mask, handy with a breakpoint or state variant:

```tsx
<div className="scroll-fade-x md:scroll-fade-none overflow-x-auto" />
```

## Browser support [#browser-support]

The scroll awareness uses CSS scroll-driven animations
(`animation-timeline: scroll()`), with no JavaScript. Browsers without them get
a static fade on every covered edge. Content is never hidden; it just loses the
"you've reached the end" polish.

## Accessibility [#accessibility]

- The fade is visual only. Every item stays in the DOM and reachable.
- A scroller without focusable children needs `tabIndex={0}`, `role="region"`
  and an `aria-label`, or keyboards can't scroll it.
- Put `role="region"` on a wrapper `div`, not on the `ul`, so the list keeps its
  list semantics.
- The mask clips focus rings on the scroller. Show focus on a parent instead,
  for example `has-focus-visible:ring-3`.
- Don't fade so much that the first or last item gets hard to read.

## Reference [#reference]

[shadcn/ui - scroll-fade](https://ui.shadcn.com/docs/utils/scroll-fade)

# Select (/docs/ui/select)

## Preview [#preview]

## Usage [#usage]

Options come from the `z.enum`. `labels` names them; a value without a label
shows as is.

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormSelect } from '@vitnode/core/components/form/fields/select'

const formSchema = z.object({
  visibility: z.enum(['public', 'members', 'staff']).default('public'),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'visibility',
      component: (props) => (
        <AutoFormSelect
          {...props}
          label="Visibility"
          labels={[
            { value: 'public', label: 'Everyone' },
            { value: 'members', label: 'Signed-in members' },
            { value: 'staff', label: 'Staff only' },
          ]}
        />
      ),
    },
  ]}
/>
```

</Tab>

```tsx
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@vitnode/core/components/ui/select'

const items = [
  { label: 'Everyone', value: 'public' },
  { label: 'Staff only', value: 'staff' },
]

;<Select items={items}>
  <SelectTrigger>
    <SelectValue placeholder="Pick visibility" />
  </SelectTrigger>
  <SelectContent>
    {items.map((item) => (
      <SelectItem key={item.value} value={item.value}>
        {item.label}
      </SelectItem>
    ))}
  </SelectContent>
</Select>
```

Pass `items` to `Select` so `SelectValue` shows the label. Without it you get
the raw `value`.

</Tab>
</Tabs>

## Groups and sizes [#groups-and-sizes]

`SelectGroup` + `SelectLabel` add headings, `SelectSeparator` draws a line.
`SelectTrigger` takes `size="sm"` for toolbars and filters.

```tsx
<SelectTrigger size="sm">
  <SelectValue />
</SelectTrigger>
<SelectContent>
  <SelectGroup>
    <SelectLabel>Members</SelectLabel>
    <SelectItem value="newest">Newest first</SelectItem>
  </SelectGroup>
  <SelectSeparator />
</SelectContent>
```

Give a manual select a label, for example with `aria-labelledby` on the
trigger. `AutoFormSelect` does it for you.

## Motion and touch [#motion-and-touch]

- The chevron flips and the list scales in from the trigger. Reduced motion
  turns both off.
- On touch screens the trigger's tap area grows to 44px and options get taller.
- Scrolling a long list never drags the page along.

## Props [#props]

`AutoFormSelect` also passes [Base UI Select](https://base-ui.com/react/components/select#api-reference)
root props through, like `disabled` and `onValueChange`.

# Separator (/docs/ui/separator)

## Preview [#preview]

## Usage [#usage]

```ts
import { Separator } from '@vitnode/core/components/ui/separator'
```

```tsx
<Separator />
```

## Vertical [#vertical]

`orientation="vertical"` draws a vertical line at the parent's full height, so
give the row a height:

```tsx
<div className="flex h-5 items-center gap-4">
  <span>Forum</span>
  <Separator orientation="vertical" />
  <span>Blog</span>
</div>
```

## Accessibility [#accessibility]

It renders `role="separator"` with the matching `aria-orientation`, so screen
readers know where one group ends.

## API Reference [#api-reference]

[Base UI - Separator](https://base-ui.com/react/components/separator#api-reference)

# Sheet (/docs/ui/sheet)

## Preview [#preview]

## Usage [#usage]

```ts
import { Button } from '@vitnode/core/components/ui/button'
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from '@vitnode/core/components/ui/sheet'
```

```tsx
<Sheet>
  <SheetTrigger render={<Button variant="outline">Notifications</Button>} />
  <SheetContent>
    <SheetHeader>
      <SheetTitle>Notifications</SheetTitle>
      <SheetDescription>Pick what lands in your inbox.</SheetDescription>
    </SheetHeader>
    <SheetFooter>
      <SheetClose render={<Button variant="outline">Done</Button>} />
    </SheetFooter>
  </SheetContent>
</Sheet>
```

`SheetHeader` and `SheetFooter` bring their own padding. Give the content
between them `px-4` to line up.

## Side [#side]

`side` picks the edge: `right` (default), `left`, `top` or `bottom`. Left and
right sheets take 3/4 of a phone screen and cap at `max-w-sm` from `sm` up.

```tsx
<SheetContent side="left">...</SheetContent>
```

## Forms [#forms]

A sheet suits short settings: a handful of fields about one thing. Place the
fields with `layout` in a scrollable body, and end with `AutoFormSheetFooter`.
It shows an "Unsaved changes" note, a Cancel button that closes the sheet, and
a Save button that stays disabled until something changes.

```tsx
import { AutoFormSheetFooter } from '@vitnode/core/components/form/auto-form-sheet-footer'
```

```tsx
const [open, setOpen] = React.useState(false)

<Sheet onOpenChange={setOpen} open={open}>
  <SheetContent className="w-full gap-0 data-[side=right]:w-full data-[side=right]:sm:max-w-lg">
    <SheetHeader className="border-b pe-14">
      <SheetTitle>Welcome message</SheetTitle>
    </SheetHeader>
    <AutoForm
      className="flex min-h-0 flex-1 flex-col gap-0"
      fields={fields}
      formSchema={formSchema}
      layout={(rendered) => (
        <>
          <div className="flex min-h-0 flex-1 flex-col gap-5 overflow-y-auto px-4 py-5">
            {rendered.enabled}
            {rendered.welcome}
          </div>
          <AutoFormSheetFooter submitLabel="Save message" />
        </>
      )}
      onSubmit={async (values) => {
        await save(values)
        setOpen(false)
      }}
    />
  </SheetContent>
</Sheet>
```

Control `open` so a successful save can close the sheet. Pass `disabled` to the
footer when the viewer may only read the settings.

### Sheet, dialog or page? [#sheet-dialog-or-page]

Choose the surface by how much there is to edit:

## Sheet or Drawer? [#sheet-or-drawer]

A sheet is a dialog that slides. A [Drawer](/docs/ui/drawer) also follows your
finger and closes with a swipe, which feels better on phones.

## Props [#props]

Both props live on `SheetContent`. `Sheet` takes `open` and `onOpenChange` like
a [Dialog](/docs/ui/dialog).

## API Reference [#api-reference]

[Base UI - Dialog](https://base-ui.com/react/components/dialog#api-reference)

# Shimmer (/docs/ui/shimmer)

## Preview [#preview]

## Usage [#usage]

Shimmer is a Tailwind utility, not a component, so there's nothing to import.
It ships with the `shadcn` package, which VitNode apps already load in
`src/styles.css`:

```css
@import 'shadcn/tailwind.css';
```

```tsx
<p className="shimmer text-muted-foreground">Generating response...</p>
```

The highlight comes from `currentColor`, so it works on any text color, and it
brightens on its own in dark mode. One sweep takes two seconds, then loops.

## Variants [#variants]

| Class                     | What it does                                                     |
| ------------------------- | ---------------------------------------------------------------- |
| `shimmer`                 | Turns the effect on                                              |
| `shimmer-color-<color>`   | Highlight color: theme color, `/opacity` or `[#378ADD]`          |
| `shimmer-duration-<ms>`   | One sweep in milliseconds (default 2000)                         |
| `shimmer-spread-<number>` | Band width on the spacing scale, or `[30%]` (default 3ch + 40px) |
| `shimmer-angle-<number>`  | Band tilt in degrees (default 20)                                |
| `shimmer-reverse`         | Sweeps against the reading direction                             |
| `shimmer-once`            | Plays a single sweep                                             |
| `shimmer-none`            | Turns it off, in any class order                                 |

The sweep follows the reading direction, so it runs right to left in RTL.

## Play once [#play-once]

`shimmer-once` makes a nice "done!" when streaming finishes. Change the
element's `key` to replay it.

```tsx
<p className="shimmer shimmer-once shimmer-duration-1100" key={replays}>
  Response generated.
</p>
```

## Turning it off [#turning-it-off]

`shimmer-none` wins regardless of class order, so it works with breakpoints and
state variants:

```tsx
<p className="shimmer md:shimmer-none">Generating response...</p>
```

## With a status line [#with-a-status-line]

Pair it with a `Spinner` and a [Marker](/docs/ui/marker):

```tsx
<Marker role="status">
  <MarkerIcon>
    <Spinner />
  </MarkerIcon>
  <MarkerContent className="shimmer">Thinking...</MarkerContent>
</Marker>
```

## Browser support [#browser-support]

Shimmer needs relative color syntax and `color-mix()`, which every current
browser has. Older ones may render the text transparent. To be safe, apply it
only where it works:

```tsx
<p className="supports-[color:oklch(from_white_l_c_h)]:shimmer">
  Generating response...
</p>
```

## Accessibility [#accessibility]

- Reduced motion stops the animation automatically, but only for the plain
  `shimmer` class. Behind a variant (`group-hover:shimmer`), add
  `motion-reduce:shimmer-none` yourself.
- Shimmer is decoration, not a loading signal. Put real text inside
  `role="status"`, like "Thinking...".
- Keep it on short status text. A whole sparkling paragraph is more disco than
  progress.

## Reference [#reference]

[shadcn/ui - shimmer](https://ui.shadcn.com/docs/utils/shimmer)

# Skeleton (/docs/ui/skeleton)

## Usage [#usage]

```ts
import { Skeleton } from '@vitnode/core/components/ui/skeleton'
```

```tsx
<Skeleton className="size-12 rounded-full" />
<Skeleton className="h-4 w-full" />
```

Size and shape it with `className`. It's a muted block with rounded corners
and nothing else.

## Match the real layout [#match-the-real-layout]

Build the skeleton from the same parts as the loaded UI, so nothing jumps when
the data arrives.

```tsx
<div aria-busy={isLoading}>{isLoading ? <ThreadSkeleton /> : <Thread />}</div>
```

## Accessibility [#accessibility]

- A skeleton is decoration and ships with `aria-hidden="true"`. Mark the
  region that's loading with `aria-busy="true"` instead.
- The pulse only plays when reduced motion is off. Otherwise it holds still.

# Spacing & Layout (/docs/ui/spacing)

Every gap, padding and margin in VitNode comes from one scale. Pick a step,
never a pixel, and layouts line up on their own.

## Spacing scale [#spacing-scale]

One unit is `0.25rem` (4px), so `p-4` is 16px and `gap-6` is 24px. Stay on the
scale: `p-4`, never `p-[16px]`.

## Gap, not space-\* [#gap-not-space-]

Hit **Add tags** until the rows wrap. `space-x-*` puts margins on children, so
wrapped rows touch and hidden items leave holes. `gap-*` belongs to the parent
and just works.

```tsx
<ul className="flex flex-wrap gap-2">{tags}</ul>
```

Never mix margin or padding with `gap` on the same element. One job, one tool.

## Group by proximity [#group-by-proximity]

Distance is meaning. Things that belong together sit closer than things that
don't: `gap-1` for a title and its hint, `gap-2` for a label and its input,
`gap-8` between sections.

## Cards bring their own padding [#cards-bring-their-own-padding]

`Card` sets `--card-spacing` once (24px, or 16px with `size="sm"`) and every
part reuses it. Don't pad the card again, use `CardHeader` and `CardContent`.

## Responsive layout [#responsive-layout]

Drag the handle. Container queries (`@container` + `@md:`) react to the box a
component lives in, so the same widget works in a sidebar and a full page.

Page layouts use viewport breakpoints, mobile first: write the phone layout,
then add `sm:`, `md:`, `lg:` on top.

| `sm`   | `md`   | `lg`   | `xl`   | `2xl`  |
| ------ | ------ | ------ | ------ | ------ |
| 640px  | 768px  | 1024px | 1280px | 1536px |

`useIsMobile()` flips at `md` (768px), so CSS and JS agree on what a phone is.

## Logical properties for RTL [#logical-properties-for-rtl]

Switch to `pl-` / `ml-` and watch the Arabic row break. `ps-`, `pe-`, `ms-`,
`me-`, `start-` and `border-s` follow the reading direction, so one class list
serves both.

```tsx
<div className="flex items-center gap-3 border-s-4 ps-3">
  <ChevronRightIcon className="ms-auto rtl:rotate-180" />
</div>
```

## Layout rules [#layout-rules]

- `flex` and `grid` with `gap-*` for layout. No floats, and absolute
  positioning only for real overlays.
- Semantic alignment: `items-center`, `justify-between`, `self-end`.
- Mobile first: the base class is the phone, prefixes add space.
- `max-w-prose` (65ch) on long paragraphs, so lines stay easy to follow on a
  wide monitor.

## Related [#related]

# Spinner (/docs/ui/spinner)

## Usage [#usage]

```ts
import { Spinner } from '@vitnode/core/components/ui/spinner'
```

```tsx
<Spinner size="lg" className="text-primary" />
```

It takes the text color around it, so a color change is one `text-*` class.

| Size      | Pixels | Good for                          |
| --------- | ------ | --------------------------------- |
| `sm`      | 12     | Badges, dense rows                |
| `default` | 16     | Buttons, inputs, inline with text |
| `lg`      | 24     | Cards and panels                  |
| `xl`      | 40     | A whole page or section           |

## In buttons [#in-buttons]

Prefer `isLoading` on [Button](/docs/ui/button). It swaps the label for a
spinner, disables the button and announces "Loading". Add a `Spinner` by hand
to keep the label visible.

```tsx
<Button disabled>
  <Spinner aria-hidden="true" />
  Uploading...
</Button>
```

## In badges, inputs and text [#in-badges-inputs-and-text]

```tsx
<InputGroupAddon align="inline-end">
  <Spinner aria-label="Searching" />
</InputGroupAddon>
```

## Loading states [#loading-states]

Put it in an [Empty](/docs/ui/empty) state, or over a card that's refreshing.
For a Suspense fallback, center an `xl` spinner, like the AdminCP does.

```tsx
<Suspense
  fallback={
    <div className="flex items-center justify-center">
      <Spinner size="xl" />
    </div>
  }
>
  <SlowThing />
</Suspense>
```

Know what's coming? A [Skeleton](/docs/ui/skeleton) of that shape usually feels
faster.

## Accessibility [#accessibility]

- A spinner has `role="status"` and the label "Loading", translated. Pass
  `aria-label` for something specific, like "Searching".
- If nearby text already says what's happening, add `aria-hidden="true"` so
  screen readers don't hear it twice.
- Mark the loading container with `aria-busy="true"`.

## Props [#props]

# Switch (/docs/ui/switch)

## Preview [#preview]

## Usage [#usage]

```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormSwitch } from '@vitnode/core/components/form/fields/switch'
import { z } from 'zod'

const formSchema = z.object({
  maintenance: z.boolean().default(false),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'maintenance',
      component: (props) => (
        <AutoFormSwitch {...props} label="Maintenance mode" />
      ),
    },
  ]}
/>
```

</Tab>
  <Tab value="Manual">

```tsx
import { Switch } from '@vitnode/core/components/ui/switch'
```

```tsx
<Switch aria-label="Maintenance mode" checked={on} onCheckedChange={setOn} />
```

</Tab>
</Tabs>

## States [#states]

- `size="sm"` fits dense lists. The default is `"default"`.
- `disabled` dims it. Add `data-disabled` to the parent [Field](/docs/ui/field)
  to dim the label too.
- `aria-invalid` adds a red ring. Point `aria-describedby` at the error.

```tsx
<Field orientation="horizontal">
  <FieldLabel htmlFor="compact">Compact thread list</FieldLabel>
  <Switch id="compact" size="sm" />
</Field>
```

## Nested fields [#nested-fields]

`AutoFormSwitch` can reveal the settings it controls in the same card. See
[Auto Form - Nested fields](/docs/ui/auto-form#nested-fields).

## Props [#props]

Every [Base UI Switch](https://base-ui.com/react/components/switch#api-reference)
prop works too.

## API Reference [#api-reference]

[Base UI - Switch](https://base-ui.com/react/components/switch#api-reference)

# Tabs (/docs/ui/tabs)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsPanels,
  TabsTrigger,
} from '@vitnode/core/components/ui/tabs'
```

```tsx
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
  </TabsList>

<TabsPanels>
    <TabsContent value="overview">Overview panel</TabsContent>
    <TabsContent value="activity">Activity panel</TabsContent>
  </TabsPanels>
</Tabs>
```

## Motion [#motion]

Click around the preview. Three things move, on the same easing:

- **The indicator** slides and resizes to the active tab. `TabsList` renders it
  for you.
- **The panels** crossfade and drift in the direction you travelled: pick a tab
  to the right and the new panel arrives from the right.
- **The panel area** animates its height, so the page (or dialog) never jumps.

Under reduced motion, nothing slides or resizes. Panels just crossfade.

## TabsPanels is required [#tabspanels-is-required]

`TabsPanels` measures the panels, animates the height and clips the outgoing
panel. Always wrap `TabsContent` in it. Don't add padding: it carries its own,
so focus rings aren't clipped.

## Line variant [#line-variant]

An underline instead of a filled pill. Same motion.

```tsx
<TabsList variant="line">
```

## Vertical [#vertical]

Triggers stack beside the panels. The indicator and panels move up and down.

```tsx
<Tabs defaultValue="general" orientation="vertical">
```

## Keep panels mounted [#keep-panels-mounted]

Inactive panels unmount. In forms, a field on a hidden tab must still submit,
so pass `keepMounted`. [Auto Form](/docs/ui/auto-form) does this for its tabs.

```tsx
<TabsContent keepMounted value="overview">
```

## API Reference [#api-reference]

[Base UI - Tabs](https://base-ui.com/react/components/tabs)

# Textarea (/docs/ui/textarea)

## Preview [#preview]

## Usage [#usage]

```tsx
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormTextarea } from '@vitnode/core/components/form/fields/textarea'
import { z } from 'zod'

const formSchema = z.object({
  about: z.string().min(10, 'At least 10 characters').max(500).default(''),
})
```

```tsx
<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'about',
      component: (props) => (
        <AutoFormTextarea
          {...props}
          label="About"
          description="Shown on your community's home page."
        />
      ),
    },
  ]}
/>
```

</Tab>
  <Tab value="Manual">

```tsx
import { Textarea } from '@vitnode/core/components/ui/textarea'
```

```tsx
<Textarea aria-label="Reply" placeholder="Keep it kind." />
```

</Tab>
</Tabs>

## States [#states]

The textarea grows with its content (`field-sizing: content`), starting at
`min-h-16`. Add `max-h-*` to cap it. Set `aria-invalid` for the error style and `disabled` to dim it.

```tsx
<Textarea aria-invalid aria-describedby="report-error" id="report" />
```

## Character counter [#character-counter]

Pass `InputGroupAddon` children to `AutoFormTextarea` for a footer, like a
live counter. See [Input Group](/docs/ui/input-group#with-autoform).

## Multi-language [#multi-language]

`multiLang` works here too. A language select appears next to the label. See
[Auto Form - Multi-language fields](/docs/ui/auto-form#multi-language-fields).

```tsx
<AutoFormTextarea {...props} label="Rules" multiLang />
```

## Props [#props]

`AutoFormTextarea` also accepts every native `<textarea>` prop.

# Toast (/docs/ui/toast)

## Preview [#preview]

## Usage [#usage]

VitNode mounts the toaster for you. Call `toast` from
[Sonner](https://sonner.emilkowal.ski/):

```ts
import { toast } from 'sonner'

toast.success('Post published', {
  description: 'Your reply is live in "Login fails after reset".',
})
```

## Variants [#variants]

A variant tints the icon, title and action button. The card stays neutral.

```ts
toast('Thread moved')
toast.info('Maintenance tonight')
toast.success('Post published')
toast.warning('Running low on storage')
toast.error('Could not save the post')
```

- `success`: it worked the way the user hoped.
- `info`: good to know, nothing to worry about.
- `warning`: nothing broke yet, but take a look.
- `error`: it failed. Say what to do next in the `description`.

After a create, edit or delete, always add a `description` saying what changed.

## Actions [#actions]

`action` adds a button in the variant's colour. `cancel` adds a quieter second
one.

```ts
toast('Thread archived', {
  action: { label: 'Undo', onClick: () => restoreThread(id) },
})
```

## Avatars and messages [#avatars-and-messages]

`ToastAvatar` swaps the icon for a picture, for things a person did. Without a
`src`, or while loading, it shows the first letter of `alt`. Any element works
as `icon`.

```tsx
import { ToastAvatar, ToastMessage } from '@vitnode/core/components/ui/sonner'

toast('Ada Lovelace invited you', {
  icon: <ToastAvatar alt="Ada Lovelace" src={user.avatarUrl} />,
})
```

For replies, mentions and DMs, render `ToastMessage` with `toast.custom`. It
lays out avatar, sender, time, text and buttons. Give it a longer `duration`:
people need time to read and decide.

```tsx
toast.custom(
  (id) => (
    <ToastMessage
      actions={[
        {
          label: 'Dismiss',
          onClick: () => toast.dismiss(id),
          variant: 'outline',
        },
        { label: 'Reply', onClick: () => openReply(message) },
      ]}
      avatar={{ alt: 'Alex Johnson', src: user.avatarUrl }}
      description="Hey! I've finished the design review."
      time="2m ago"
      title="Alex Johnson"
    />
  ),
  { duration: 10000 },
)
```

## Promises [#promises]

`toast.promise` spins while the promise runs, then switches to success or error.

```ts
toast.promise(publishArticle(), {
  loading: 'Publishing your article...',
  success: 'Article published',
  error: 'Could not publish the article',
})
```

## Placement and styles [#placement-and-styles]

Toasts live in the **top-right** corner and stretch full width on phones.
`VitNodeRootProviders` in `src/routes/__root.tsx` takes a `toaster` prop to
move them (`top-left`, `top-center`, `bottom-left`, `bottom-center`,
`bottom-right`):

```tsx
<VitNodeRootProviders config={config} toaster={{ position: 'bottom-center' }}>
  {children}
</VitNodeRootProviders>
```

Pass `classNames` to restyle one toast. Your classes merge with the defaults:

```ts
toast('Saved', { classNames: { title: 'font-semibold' } })
```

## Accessibility [#accessibility]

- Toasts are announced through a polite live region.
- Hovering pauses the timer. <kbd>Alt</kbd> + <kbd>T</kbd> jumps to the toasts.
- The close button shows on hover and focus, always on touch, with a hit area
  up to 44px.
- Every variant has its own icon, so colour is never the only signal.

## Documentation [#documentation]

[Sonner Documentation](https://sonner.emilkowal.ski/)

# Toggle Group (/docs/ui/toggle-group)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  ToggleGroup,
  ToggleGroupItem,
} from '@vitnode/core/components/ui/toggle-group'
```

```tsx
<ToggleGroup aria-label="Text formatting" multiple variant="outline">
  <ToggleGroupItem aria-label="Bold" value="bold">
    <BoldIcon />
  </ToggleGroupItem>
  <ToggleGroupItem aria-label="Italic" value="italic">
    <ItalicIcon />
  </ToggleGroupItem>
</ToggleGroup>
```

`variant` and `size` go on the group, and every item follows.

## Single selection [#single-selection]

Leave out `multiple` and only one item can be pressed. The pressed background
glides between items, and jumps when the visitor prefers reduced motion.

```tsx
<ToggleGroup defaultValue={['week']} variant="outline">
  <ToggleGroupItem value="day">Day</ToggleGroupItem>
  <ToggleGroupItem value="week">Week</ToggleGroupItem>
  <ToggleGroupItem value="month">Month</ToggleGroupItem>
</ToggleGroup>
```

The value is always an array, even in single mode. Clicking the pressed item
empties it, so ignore empty arrays in `onValueChange` when one option must stay
picked:

```tsx
<ToggleGroup
  onValueChange={(next) => {
    if (next.length > 0) setValue(next);
  }}
  value={value}
>
```

## Spacing and orientation [#spacing-and-orientation]

`spacing` pulls the items apart on the spacing scale. At `0` (the default) they
share borders. `orientation="vertical"` stacks them.

```tsx
<ToggleGroup spacing={2} variant="outline">...</ToggleGroup>
<ToggleGroup orientation="vertical" variant="outline">...</ToggleGroup>
```

## Accessibility [#accessibility]

- Give the group an `aria-label` and every icon-only item its own.
- Arrow keys move focus between items, and <kbd>Space</kbd> or <kbd>Enter</kbd>
  presses one.

## Props [#props]

<TypeTable
  type={{
    multiple: {
      description: 'Allow more than one pressed item.',
      type: 'boolean',
      default: 'false',
    },
    value: {
      description: 'Controlled pressed values.',
      type: 'string[]',
    },
    defaultValue: {
      description: 'Initial pressed values when uncontrolled.',
      type: 'string[]',
    },
    onValueChange: {
      description: 'Called with the new pressed values.',
      type: '(value: string[], eventDetails) => void',
    },
    variant: {
      description: 'Visual style for every item.',
      type: 'default | outline',
      default: 'default',
    },
    size: {
      description: 'Size for every item.',
      type: 'sm | default | lg',
      default: 'default',
    },
    spacing: {
      description: 'Gap between items on the spacing scale. 0 joins them.',
      type: 'number',
      default: '0',
    },
    orientation: {
      description: 'Lays items out in a row or a column.',
      type: 'horizontal | vertical',
      default: 'horizontal',
    },
  }}
/>

## API Reference [#api-reference]

[Base UI - Toggle Group](https://base-ui.com/react/components/toggle-group)

# Toggle (/docs/ui/toggle)

## Preview [#preview]

## Usage [#usage]

```ts
import { Toggle } from '@vitnode/core/components/ui/toggle'
```

```tsx
<Toggle aria-label="Bold">
  <BoldIcon />
</Toggle>
```

A toggle is a button with memory. Screen readers hear it as pressed or not
pressed, thanks to `aria-pressed`.

## Controlled [#controlled]

```tsx
<Toggle onPressedChange={setIsWatching} pressed={isWatching}>
  Watch thread
</Toggle>
```

Pair `pressed` with `onPressedChange`, or use `defaultPressed` when you don't
need the state.

## Outline [#outline]

The `outline` variant adds a border, so the toggle reads as a control even when
it's off.

```tsx
<Toggle aria-label="Pin topic" variant="outline">
  <PinIcon />
</Toggle>
```

## Sizes [#sizes]

## With text [#with-text]

Put `data-icon="inline-start"` (or `inline-end`) on the icon to tighten the
padding on that side.

```tsx
<Toggle variant="outline">
  <BookmarkIcon data-icon="inline-start" />
  Bookmark
</Toggle>
```

## Disabled [#disabled]

```tsx
<Toggle disabled>Lock topic</Toggle>
```

## Accessibility [#accessibility]

- Icon-only toggles need an `aria-label`.
- Keep the label the same in both states. "Bold" pressed says it all;
  swapping it to "Not bold" confuses screen readers.
- Need several related toggles? Use [Toggle Group](/docs/ui/toggle-group).

## Props [#props]

<TypeTable
  type={{
    variant: {
      description: 'Visual style.',
      type: 'default | outline',
      default: 'default',
    },
    size: {
      description: 'Height and padding.',
      type: 'sm | default | lg',
      default: 'default',
    },
    pressed: {
      description: 'Controlled pressed state.',
      type: 'boolean',
    },
    defaultPressed: {
      description: 'Initial pressed state when uncontrolled.',
      type: 'boolean',
      default: 'false',
    },
    onPressedChange: {
      description: 'Called when the pressed state changes.',
      type: '(pressed: boolean, eventDetails) => void',
    },
    disabled: {
      description: 'Blocks interaction.',
      type: 'boolean',
      default: 'false',
    },
  }}
/>

## API Reference [#api-reference]

[Base UI - Toggle](https://base-ui.com/react/components/toggle)

# Tooltip (/docs/ui/tooltip)

## Preview [#preview]

## Usage [#usage]

```ts
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from '@vitnode/core/components/ui/tooltip'
```

```tsx
<Tooltip>
  <TooltipTrigger
    render={
      <Button aria-label="Bookmark thread" size="icon" variant="outline">
        <BookmarkIcon />
      </Button>
    }
  />
  <TooltipContent>Bookmark thread</TooltipContent>
</Tooltip>
```

A tooltip is a hint, not a label. Icon buttons still need their own
`aria-label`.

## Shorter syntax [#shorter-syntax]

`TooltipWithContent` does the same in one component when you don't need props
on the trigger.

```ts
import { TooltipWithContent } from '@vitnode/core/components/ui/tooltip'
```

```tsx
<TooltipWithContent text="Reply">
  <Button aria-label="Reply" size="icon" variant="ghost">
    <MessageSquareIcon />
  </Button>
</TooltipWithContent>
```

## Delay and warm-up [#delay-and-warm-up]

Tooltips wait 200ms, so they don't flash as the cursor passes by. Once one is
open, its neighbours open instantly. Hover the left row, then slide along it.

VitNode already mounts a `TooltipProvider` for the whole app. Wrap a section in
another one to change its timing:

```tsx
<TooltipProvider delay={0}>
  <Toolbar />
</TooltipProvider>
```

## Side and shortcuts [#side-and-shortcuts]

`TooltipContent` takes `side` (default `top`), `align` and `sideOffset`
(default `8`). Drop a `Kbd` inside to show a shortcut. It restyles itself for
the dark tooltip.

```tsx
<TooltipContent side="right">
  Save draft
  <KbdGroup>
    <Kbd>⌘</Kbd>
    <Kbd>S</Kbd>
  </KbdGroup>
</TooltipContent>
```

## Group [#group]

In a toolbar, wrap the buttons in `TooltipGroup` and use `TooltipGroupTrigger`.
They share one tooltip that glides from button to button, resizes to fit and
slides the text in from the direction you came.

```ts
import {
  TooltipGroup,
  TooltipGroupTrigger,
} from '@vitnode/core/components/ui/tooltip'
```

```tsx
<TooltipGroup>
  <div aria-label="Formatting" role="toolbar">
    <TooltipGroupTrigger
      content="Bold"
      render={<Button aria-label="Bold" size="icon-sm" variant="ghost" />}
    >
      <BoldIcon />
    </TooltipGroupTrigger>
  </div>
</TooltipGroup>
```

`TooltipGroup` takes `side`, `sideOffset` and `align`. A `TooltipWithContent`
without extra props joins the group on its own. With reduced motion on, the
tooltip jumps instead of gliding.

## Props [#props]

## API Reference [#api-reference]

[Base UI - Tooltip](https://base-ui.com/react/components/tooltip)

# Typography (/docs/ui/typography)

VitNode uses each device's own system font and a type scale that already knows
its letter spacing. Zero font downloads, zero layout shift.

## Font [#font]

`font-sans` is the system UI stack: San Francisco on Apple devices, Segoe UI on
Windows, Roboto on Android. Swap `--font-sans` in `src/styles.css` for a brand
font. Stick to three weights: `font-normal`, `font-medium`, `font-semibold`.

## Type scale [#type-scale]

Every `text-*` size carries its own tracking: tighter as it grows, a little air
at `text-xs`. Pick the size and you're done. Don't add `tracking-tight` on top.
Sizes are `rem`, so the UI scales with the reader's browser font size.

## Hierarchy [#hierarchy]

A few clear steps beat many similar ones. Weight and color do as much work as
size.

```tsx
<h2 className="text-2xl font-semibold text-balance">Notifications</h2>
<p className="text-muted-foreground text-sm leading-relaxed">
  Choose what lands in your inbox.
</p>
```

## Balanced headings [#balanced-headings]

`text-balance` evens out heading lines, so no word is left alone. Use
`text-pretty` on paragraphs.

## Numbers that change [#numbers-that-change]

`tabular-nums` gives every digit the same width, so counters, prices and table
columns stop jiggling.

```tsx
<span className="tabular-nums">{onlineCount} online</span>
```

## Body text rules [#body-text-rules]

- `leading-relaxed` on paragraphs, never below `text-sm` (14px) for reading.
- `max-w-prose` for long text.
- `text-xs` only for labels, badges and timestamps.

## Related [#related]

# User (/docs/ui/user)

## Preview [#preview]

## Usage [#usage]

```ts
import { z } from 'zod'
import { AutoForm } from '@vitnode/core/components/form/auto-form'
import { AutoFormUser } from '@vitnode/core/components/form/fields/input-users'
import { searchAdminUsersInBrowser } from '@vitnode/core/tanstack/admin/users'
```

```tsx
const formSchema = z.object({ authorId: z.number() })

<AutoForm
  formSchema={formSchema}
  fields={[
    {
      id: 'authorId',
      component: props => (
        <AutoFormUser
          {...props}
          label="Author"
          placeholder="Select an author"
          search={searchAdminUsersInBrowser}
        />
      ),
    },
  ]}
/>
```

The value is the user id, a plain number. `search` is required. In the
AdminCP, `searchAdminUsersInBrowser` reads the AdminCP users list, so it needs
an AdminCP session and returns only what that route allows.

## Editing an existing record [#editing-an-existing-record]

A picker can't show a name it never fetched. Pass the saved person as
`selected`, or the field opens on the placeholder. `clearable` adds a button
that sets the value to `null`, so pair it with `z.number().nullable()`.

```tsx
<AutoFormUser
  {...props}
  clearable
  label="Reviewer"
  search={search}
  selected={{ id: post.reviewer.id, name: post.reviewer.name }}
/>
```

`selected` can be partial: just `id` and `name`. Without `avatarColor`, the
field draws a neutral placeholder avatar instead of guessing a color.

## Role colors [#role-colors]

Add a `role` to each option and the picker draws the name the way the rest of
the site does: in the role's color, with its prefix icon or emoji in front.
Options without a `role` keep a plain name, so you can add it gradually.

```tsx
const moderators: UserOption[] = [
  {
    avatarColor: '2563eb',
    id: 1,
    name: 'Ada Lovelace',
    nameCode: 'ada',
    role: { color: '#dc2626', prefix: 'icon:shield' },
  },
]
```

`prefix` takes the same `icon:<lucide-name>` or `emoji:<emoji>` value as a
role's prefix in the AdminCP. In the AdminCP, `searchAdminUsersInBrowser`
already returns each person's primary role, so its pickers show colored names
without extra work.

## Show a member's name [#show-a-members-name]

`UserFormat` prints a name the way the rest of the site does. `format` adds the
role color and prefix, and `link` turns the name into a link to the member's
profile at `/users/<nameCode>`.

```tsx
import { UserFormat } from '@vitnode/core/components/user-format'

<UserFormat format link user={user} />
```

`user` is `{ name, nameCode?, role: { color, prefix? } }`. `link` needs a
`nameCode`; without one, the name renders as plain text. Leave `link` off when
the name sits inside another link or a button, such as a table row that
already opens something.

## Custom search [#custom-search]

`search` can call any endpoint: a plugin's own members, fixtures in a test.
It runs with `""` each time the picker opens, then debounced as the person
types. Results are never cached, so deleted users don't linger.

```tsx
<AutoFormUser
  {...props}
  label="Reviewer"
  search={(value) => searchReviewers(value)}
/>
```

## Props [#props]

| Prop                | Type                                       | Default            | What it does                           |
| ------------------- | ------------------------------------------ | ------------------ | -------------------------------------- |
| `search`            | `(value: string) => Promise<UserOption[]>` | required           | Looks up people                        |
| `label`             | `ReactNode`                                | -                  | Field label                            |
| `description`       | `ReactNode`                                | -                  | Help text under the control            |
| `placeholder`       | `string`                                   | `Select an option` | Shown while nobody is chosen           |
| `searchPlaceholder` | `string`                                   | `Search...`        | Placeholder inside the search box      |
| `selected`          | `PartialUserOption \| null`                | -                  | The person the field opens on          |
| `clearable`         | `boolean`                                  | `false`            | Adds a button that sets `null`         |
| `disabled`          | `boolean`                                  | `false`            | Blocks opening the picker and clearing |

`UserOption` is `{ id, name, nameCode, avatarColor, role? }`, where `role` is
`{ color: string | null, prefix?: string | null }`. `PartialUserOption` makes
`nameCode` and `avatarColor` optional.

## In the Content Engine [#in-the-content-engine]

A [`field.user()`](/docs/content-engine/fields) renders this field, like
the blog post author picker. Its options come from the content type's own
picker route, so editors can pick an author without browsing the member list.

## See also [#see-also]

- [Roles](/docs/ui/roles) - the same idea for roles, single or multiple.
- [Combobox](/docs/ui/combobox) - when the options are strings, not people.

# View transitions (/docs/ui/view-transitions)

VitNode uses the browser's View Transition API in two places. Every navigation
to another page crossfades in 150ms, and the logo glides from the site header
to the docs header. Inside a page, React's
[`<ViewTransition>`](https://react.dev/reference/react/ViewTransition) animates
a component when it appears, leaves or changes.

## Page transitions [#page-transitions]

Click any link in the sidebar: the old page fades out while the new one fades
in. Your router turns this on with `navigationViewTransition`:

```tsx title="src/router.tsx"
import { navigationViewTransition } from '@vitnode/core/tanstack/view-transitions'

import { vitNodeConfig } from './vitnode.config'

const router = createTanStackRouter({
  defaultViewTransition: navigationViewTransition(
    vitNodeConfig.viewTransitions,
  ),
  // ...
})
```

The router starts the transition only after the next page has loaded, so the
old page never freezes while data is fetched. Changes that only touch the
query string, like paging a table or typing in a filter, skip the animation.

The timing lives in `@vitnode/core/styles/view-transitions.css`, which your
`styles.css` imports:

```css title="src/styles.css"
@import '@vitnode/core/styles/view-transitions.css';
```

## Morph the logo between layouts [#morph-the-logo-between-layouts]

Go to the [home page](/) and click **Docs** in the header. The logo moves and
resizes into the docs header instead of fading. Both logos carry the same
`view-transition-name`, so the browser treats them as one element:

```tsx
import { LOGO_VIEW_TRANSITION_NAME } from '@vitnode/core/tanstack/view-transitions'

;<Link style={{ viewTransitionName: LOGO_VIEW_TRANSITION_NAME }} to="/">
  <Logo />
</Link>
```

The site header already does this for the logo you set in
[`vitnode.config.ts`](/docs/dev/configuration#logo). Add the same style to a
logo in your own layout to join in.

<Callout type="warn" title="One name per page">
  A `view-transition-name` must be unique among the visible elements on a page.
  If two visible elements share a name, the browser skips the whole transition.
  Put the name on one wrapper, not on a logo component that a footer renders
  too.
</Callout>

## Animate a component with ViewTransition [#animate-a-component-with-viewtransition]

Wrap the element in `<ViewTransition>` and change state inside
`startTransition`. React animates the element with the class you pass to
`enter` or `exit`:

```tsx
import { startTransition, ViewTransition } from 'react'

{
  isOpen && (
    <ViewTransition enter="vt-slide-up" exit="vt-slide-down">
      <Notification />
    </ViewTransition>
  )
}

;<Button onClick={() => startTransition(() => setIsOpen((open) => !open))}>
  Toggle
</Button>
```

The class becomes a view transition class, so you style it with the
`::view-transition-*` pseudo-elements:

```css
@keyframes vt-slide-in {
  from {
    opacity: 0;
    translate: 0 0.5rem;
    scale: 0.97;
  }
}

@keyframes vt-slide-out {
  to {
    opacity: 0;
    translate: 0 0.25rem;
    scale: 0.98;
  }
}

::view-transition-new(.vt-slide-up) {
  animation: vt-slide-in 200ms cubic-bezier(0.23, 1, 0.32, 1) both;
}

::view-transition-old(.vt-slide-down) {
  animation: vt-slide-out 150ms cubic-bezier(0.4, 0, 1, 1) both;
}
```

The exit is shorter and travels less than the enter: once something is
dismissed, it should get out of the way. A plain `setState` outside
`startTransition` updates instantly, with no animation.

## Shared element transitions [#shared-element-transitions]

Give two `<ViewTransition>` boundaries the same `name`. When one unmounts and
the other mounts in the same transition, React morphs the first into the
second:

```tsx
<ViewTransition name={`plugin-${plugin.id}`} share="vt-morph">
  <PluginCard plugin={plugin} />
</ViewTransition>
```

Build each name from a stable id, so a list item and its detail view match.
The same uniqueness rule as the logo applies.

The browser stretches both snapshots to the morphing box by default, which
squashes text when the shape changes. Keep them at their natural size and let
the box clip them instead:

```css
::view-transition-group(.vt-morph) {
  overflow: clip;
  border-radius: var(--radius-xl);
  animation-duration: 250ms;
  animation-timing-function: cubic-bezier(0.645, 0.045, 0.355, 1);
}

::view-transition-old(.vt-morph),
::view-transition-new(.vt-morph) {
  height: 100%;
  object-fit: none;
  object-position: left top;
}
```

A shared element is already on screen, so it moves with an ease-in-out curve
rather than the ease-out used for things that appear. When the icon or title
sits in a different spot in each view, give it its own `name` too
(`${name}-mark`, `${name}-title`). It then travels on its own path instead of
showing up twice while the boxes crossfade.

## Direction with transition types [#direction-with-transition-types]

Call `addTransitionType` inside `startTransition` to tag the update, then map
each type to a class. Here **Next** slides in from the right and **Back** from
the left:

```tsx
import { addTransitionType, startTransition, ViewTransition } from 'react'

const go = (direction: 'back' | 'forward') => {
  startTransition(() => {
    addTransitionType(direction)
    setIndex((index) => index + (direction === 'forward' ? 1 : -1))
  })
}

;<ViewTransition
  default="none"
  enter={{
    back: 'vt-from-left',
    default: 'none',
    forward: 'vt-from-right',
  }}
  exit={{
    back: 'vt-to-right',
    default: 'none',
    forward: 'vt-to-left',
  }}
  key={index}
>
  <Step index={index} />
</ViewTransition>
```

Changing `key` makes React treat each step as a new element, so the old step
exits while the new one enters. Keep the card's border and background outside
the `<ViewTransition>`: snapshots are drawn above the page and ignore
`overflow: hidden`, so only content that stays inside the padding should move.

<Callout title="Why page changes don't use ViewTransition">
  TanStack Router renders a route change as a synchronous update, and React
  only runs `<ViewTransition>` animations for updates inside `startTransition`.
  That is why navigations use the router's `defaultViewTransition` and
  `<ViewTransition>` covers changes inside a page.
</Callout>

## Turn view transitions off [#turn-view-transitions-off]

Set `viewTransitions` to `false` in your shared config:

```ts title="src/vitnode.config.ts"
export const vitNodeConfig = buildConfig({
  // ...
  viewTransitions: false,
})
```

Navigations then swap pages instantly and the logo no longer morphs. The
option is `true` by default. React `<ViewTransition>` boundaries in your own
components still animate, because they don't go through the router.

## Reduced motion [#reduced-motion]

When the system asks for reduced motion, the router skips page transitions and
`view-transitions.css` turns off every view transition animation, including
your own `<ViewTransition>` classes. Browsers without the View Transition API
just swap the content instantly.

## Related [#related]