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 newsroom plugin, with a newsroom.desks collection and letters to the editor (newsroom.letter) filed into it.

Containers or a content type?Copy Anchor Link

A category could also be a content type with a relation. Pick a container when the thing organizes content rather than being content itself:

A record belongs to one container. For anything else it points at, such as tags, keep using relations.

Add a container collectionCopy Anchor Link

You need a content type to file into containers, like newsroom.letter from Member writing.

import { defineContentContainer, field } from "@vitnode/core/content";

export const deskContainers = defineContentContainer({
  id: "newsroom.desks",

  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: "desks",
    fields: ["description", "color", "icon"],
  },

  admin: { path: "newsroom/desks" },
});

import { deskContainers } from "@/content/desks"; 

export const letterContentType = defineContentType({
  id: "newsroom.letter",
  tableName: "newsroom_letters",

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

  publicApi: {
    path: "letters",
    fields: ["id", "title", "slug", "body", "desk", "publishedAt"], 
    filterableFields: ["desk"], 
  },

  publicWrite: {
    ownership: { field: "author" },
    create: { fields: ["title", "body", "desk"], status: "published" }, 
    update: { fields: ["title", "body"] },
  },
});

import { deskContainers } from "@/content/desks"; 

buildContentAdminModule({
  containers: [deskContainers], 
  contentTypes: [storyContent, letterContent],
}),

buildContentPublicModule({
  containers: [deskContainers], 
  contentTypes: [storyContent, letterContent],
}),

import { FolderTreeIcon, MailIcon, NotebookPenIcon } from "lucide-react"; 

import { deskContainers } from "@/content/desks"; 

export const adminNav = {
  pluginId: manifest.id,
  containers: [{ definition: deskContainers, icon: <FolderTreeIcon /> }], 
  contentTypes: [
    { definition: storyContentType, icon: <NotebookPenIcon /> },
    { definition: letterContentType, icon: <MailIcon /> },
  ],
} satisfies AdminNavPluginSource;

export { adminNav as adminContent } from "./nav";

{
  "newsroom": {
    "containers": {
      "desks": {
        "label": "{count, plural, one {Desk} other {Desks}}",
        "title": "Desks",
        "desc": "The desks readers send their letters to. Drag to reorder or nest desks.",
        "fields": {
          "description": "Description",
          "color": "Color",
          "icon": "Icon",
          "locked": "Locked"
        }
      }
    },
    "content": {
      "letter": { "fields": { "desk": "Desk" } }
    }
  },
  "newsroom:newsroom_desks": "Desks",
  "newsroom:newsroom_desks:can_view": "View desks",
  "newsroom:newsroom_desks:can_create": "Create desks",
  "newsroom:newsroom_desks:can_edit": "Edit and move desks",
  "newsroom:newsroom_desks:can_delete": "Delete desks"
}

bun run db:migrate

Manage containers in the AdminCPCopy Anchor Link

Open AdminCP → Newsroom → Desks (/admin/containers/newsroom/desks). 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 desk with its children nested below it. Drag a desk to reorder it among its siblings or to drop it inside another desk.
• 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 desk. A desk with child desks or with letters 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 letter into a desk or move it to another one.

A drag that breaks a rule, such as nesting a desk deeper than maxDepth or dropping it inside its own child, is refused the same way. Hierarchy and ordering lists every rule.

Check the resultCopy Anchor Link

Create a "Politics" desk with an "Elections" desk inside it, then read the public tree:

curl http://localhost:3000/api/newsroom/content/desks

{
  "items": [
    {
      "id": 1,
      "parentId": null,
      "name": "Politics",
      "slug": "politics",
      "position": 0,
      "depth": 1,
      "metadata": {
        "description": "Parliament, parties and policy",
        "color": "#2563eb",
        "icon": null
      }
    },
    {
      "id": 2,
      "parentId": 1,
      "name": "Elections",
      "slug": "elections",
      "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. Container pages turns this into pages.

Definition errorsCopy Anchor Link

defineContentContainer and the boot checks throw a ContentEngineError before the app serves a request:

RelatedCopy Anchor Link

• Hierarchy and ordering: depth, moves, safe deletion and the server-side service.
• Container pages: a desk tree, a desk page and a create form with a desk picker.
• Publishing rules: who may post in each desk, whether posts wait for approval, and how long authors may edit.

Read permissions per container, such as desks hidden from guests, are not available yet. Today every reader sees every container in the public tree.