Relations

A relation stores another record's id in a real foreign key column. This guide adds a newsroom.category content type and files each article under one category, which staff pick in the AdminCP.

Before you beginCopy Anchor Link

You need the newsroom.article type from First content type, with its plugin in plugins/newsroom/, and an AdminCP account. Nothing else is required. The steps and the check below work in the AdminCP alone. If you followed later guides, keep their additions. This guide only adds files, one field and one list column.

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

export const categoryContentType = defineContentType({
  id: "newsroom.category",
  tableName: "newsroom_categories",

  fields: {
    name: field.text({ required: true, minLength: 2, maxLength: 80 }),
    slug: field.slug({ source: "name" }),
  },

  admin: {
    path: "newsroom/categories",
    titleField: "name",
    list: { columns: ["name", "slug", "updatedAt"] },
  },
});

import { createContentModel } from "@vitnode/core/content/server";

import { categoryContentType } from "@/content/category";

export const categoryContent = createContentModel(categoryContentType);

export const newsroom_categories = categoryContent.table;

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

  modules: [
    buildContentAdminModule({
      contentTypes: [articleContent, categoryContent], 
    }),
  ],

import { FolderIcon, NewspaperIcon } from "lucide-react"; 

import { categoryContentType } from "@/content/category"; 

  contentTypes: [
    { definition: articleContentType, icon: <NewspaperIcon /> },
    { definition: categoryContentType, icon: <FolderIcon /> }, 
  ],

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

import { categoryContentType } from "@/content/category"; 

  fields: {
    title: field.text({ required: true, minLength: 3, maxLength: 200 }),
    slug: field.slug({ source: "title" }),
    body: field.richText({ required: true }),
    category: field.relation({
      target: () => categoryContentType,
      nullable: true,
      onDelete: "set null",
    }),
  },

  admin: {
    path: "newsroom/articles",
    titleField: "title",
    list: {
      columns: ["title", "slug", "category", "updatedAt"], 
      orderableFields: ["title"],
    },
  },

import { createContentModel } from "@vitnode/core/content/server";

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

import { newsroom_categories } from "./categories";

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

export const newsroom_articles = articleContent.table;

{
  "newsroom": {
    "content": {
      "article": {
        "fields": { "category": "Category" }
      },
      "category": {
        "label": "{count, plural, one {Category} other {Categories}}",
        "title": "Categories",
        "desc": "Sections that group the articles.",
        "fields": { "name": "Name", "slug": "Slug", "updatedAt": "Updated" }
      }
    }
  },
  "newsroom:category": "Categories",
  "newsroom:category:can_view": "View categories",
  "newsroom:category:can_create": "Create categories",
  "newsroom:category:can_edit": "Edit categories",
  "newsroom:category:can_delete": "Delete categories"
}

bun run build:plugins
bun run db:migrate

CREATE TABLE "newsroom_categories" (
	"id" serial PRIMARY KEY,
	"createdAt" timestamp DEFAULT now() NOT NULL,
	"updatedAt" timestamp DEFAULT now() NOT NULL,
	"name" varchar(80) NOT NULL,
	"slug" varchar(160) NOT NULL
);
ALTER TABLE "newsroom_articles" ADD COLUMN "category" integer;
CREATE INDEX "newsroom_articles_category_idx" ON "newsroom_articles" ("category");
ALTER TABLE "newsroom_articles" ADD CONSTRAINT "newsroom_articles_category_newsroom_categories_id_fkey" FOREIGN KEY ("category") REFERENCES "newsroom_categories"("id") ON DELETE SET NULL ON UPDATE CASCADE;

Check the resultCopy Anchor Link

Open AdminCP → Newsroom → Categories, click Create Category, enter Announcements and click Create:

Open Newsroom → Articles and click the pencil on Welcome to the newsroom. The dialog now ends with a Category picker. Choose Announcements and click Save changes:

The list shows the category's name in the new column, and the other articles show a dash:

Now delete the category. In Newsroom → Categories, click the trash button in the Announcements row and confirm with Yes, delete it. Back in Newsroom → Articles, Welcome to the newsroom shows a dash again. The article stays, and only its category became null, because the relation says onDelete: "set null".

Read the category through the public APICopy Anchor Link

This optional part needs the article's public API from Public API, which builds on Drafts & publishing, and a published article with a category. Assign a category again if you deleted it above.

Add "category" to publicApi.fields in src/content/article.ts. Change only that list, and keep every other option you configured, such as listFields, searchableFields and orderableFields:

  publicApi: {
    path: "news",
    fields: ["id", "title", "slug", "body", "category", "publishedAt"], 
    // listFields, searchableFields, orderableFields and the rest stay as they are
  },

listFields decides what the list route returns. Add "category" there too only if list rows need it. Then request the article:

curl "http://localhost:3000/api/newsroom/content/news/welcome-to-the-newsroom"

{
  "id": 1,
  "title": "Welcome to the newsroom",
  "slug": "welcome-to-the-newsroom",
  "category": { "id": 1 },
  "publishedAt": "2026-10-23T18:57:51.156Z"
}

A relation exposes only the related record's id, here the category's. The category's name is not part of the article's public answer. The AdminCP can show it because its staff list route adds a labels object with the names, and staff routes are not public.

Go furtherCopy Anchor Link

• Show the category name to readers. Give the category type publication: true and its own public API, then read the category by id or list categories next to the articles. Or model categories as containers, which bring their own pages and filters.
• Let members choose a category. Add category to publicWrite.create.fields. Members may only link to records readers can see, so the category type then needs publication: true and its own publicApi. Without them, the write route stops with an error that names the field.
• Many categories, grouped fields, repeatable rows and mixed id types. See Advanced fields.