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.

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 helpersCopy Anchor Link

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.

Shared optionsCopy Anchor Link

Every helper except slug, repeatable and blocks accepts these:

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 textareaCopy Anchor Link

code: field.text({ required: true, maxLength: 100, unique: true }),
excerpt: field.textarea({ maxLength: 500, nullable: true }),

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 textCopy Anchor Link

content: field.richText({ localized: true, required: true }),

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 covers rendering and the plain text and HTML helpers.

NumberCopy Anchor Link

views: field.number({ integer: true, min: 0, defaultValue: 0 }),

BooleanCopy Anchor Link

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.

EnumCopy Anchor Link

difficulty: field.enum({ values: ["easy", "medium", "hard"], defaultValue: "easy", display: "radio" }),

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 timeCopy Anchor Link

eventDate: field.dateTime({ defaultNow: true }),

There is no defaultValue. Send dates as ISO 8601 strings.

SlugCopy Anchor Link

slug: field.slug({ source: "title" }),

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.

UserCopy Anchor Link

author: field.user(),
authorId: field.user({ multiple: true, ordered: true, min: 1 }),

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.

FileCopy Anchor Link

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

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 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.

RelationCopy Anchor Link

category: field.relation({ required: true, onDelete: "restrict", target: () => categoryContentType }),

A single relation must be required or nullable. A to-many relation can be neither. Relations shows the model wiring and the junction tables.

GroupCopy Anchor Link

syndication: field.group({
  fields: {
    noIndex: field.boolean({ defaultValue: false }),
    priority: field.number({ integer: true, min: 0, max: 10, defaultValue: 5 }),
  },
}),

Each leaf becomes a column named <group><Leaf>, 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.

RepeatableCopy Anchor Link

faq: field.repeatable({
  max: 20,
  fields: {
    question: field.text({ required: true, minLength: 3, maxLength: 200 }),
    answer: field.textarea({ required: true }),
  },
}),

Rows live in a child table. A repeatable is always shared between languages.

BlocksCopy Anchor Link

content: field.blocks({ allowed: ["core:*", "example:callout", "example:features"], max: 50 }),

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.

AI suggestionsCopy Anchor Link

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.

excerpt: field.textarea({
  ai: {
    action: "@vitnode/example:article.excerpt",
    mode: "suggestion",
    sourceFields: ["title", "code"],
  },
  maxLength: 500,
  nullable: true,
}),

AI in fields and the editor shows how to write the action.

Searching and sortingCopy Anchor Link

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 lists which field kinds each one accepts.