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?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 example.discussion from Public write.

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" },
});

import { boardContainers } from "@/content/boards"; 

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 }), 
  },

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

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

import { boardContainers } from "@/content/boards"; 

buildContentAdminModule({
  pluginId: CONFIG_PLUGIN.pluginId,
  containers: [boardContainers], 
  contentTypes: [articleContent, discussionContent],
}),

buildContentPublicModule({
  pluginId: CONFIG_PLUGIN.pluginId,
  containers: [boardContainers], 
  contentTypes: [articleContent, discussionContent],
}),

import { FolderTreeIcon } from "lucide-react"; 

import { boardContainers } from "@/content/boards"; 

export const exampleBoardsNav = {
  definition: boardContainers,
  icon: <FolderTreeIcon />,
};

export const adminNav = {
  pluginId: CONFIG_PLUGIN.pluginId,
  containers: [exampleBoardsNav], 
  contentTypes: [exampleArticleNav, exampleDiscussionNav],
} satisfies AdminNavPluginSource;

export const adminContent = {
  pluginId: CONFIG_PLUGIN.pluginId,
  containers: [exampleBoardsNav], 
  contentTypes: [exampleArticleNav, exampleDiscussionNav],
} satisfies ContentFrontendPluginSource;

{
  "@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"
}

bun run build:plugins && bun run db:migrate

Manage containers in the AdminCPCopy Anchor Link

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 lists every rule.

Check the resultCopy Anchor Link

Create a "Frontend" board with a "React" board inside it, then read the public tree:

curl http://localhost:3000/api/@vitnode/example/content/boards

{
  "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 turns this into pages.

Definition errorsCopy Anchor Link

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

What's nextCopy Anchor Link

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: depth, moves, safe deletion and the server-side service.
• Containers on the frontend: a board tree, a board page and a create form with a board picker.