Options

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.

Minimal exampleCopy Anchor Link

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

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

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.

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

[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 optionsCopy Anchor Link

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.

NamesCopy Anchor Link

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.

adminCopy Anchor Link

Controls the generated AdminCP screens. Guide: Customize the AdminCP.

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.

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

publicationCopy Anchor Link

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 does. Guide: Publish content with a public API.

publication: true,

publicApiCopy Anchor Link

Generates read-only routes at /api/{pluginId}/content/{path} that return published records only. Guide: Publish content with a public API.

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.

people is the explicit opt-in for a user. Each named field comes back under its own name as { id, name, nameCode, avatarColor, avatarUrl, role: { color, prefix } }, or null when nobody is set or the account was deleted. A multiple: true field comes back as a list of those summaries in the order it stores them, skipping deleted accounts - handy for co-authors. The summaries for a whole page are loaded in one query. people refuses a field that is not a field.user(), a localized user field, and a name listed twice.

listFields keeps a public list light: leave a long body or a gallery to the detail route, and the list neither selects nor loads them. The list route's OpenAPI schema and the ContentPublicListRow type carry exactly these fields, so a field you left out is a compile error rather than a surprise undefined. people and, on a localized content type, locale are always included. Public lists shows listFields on the blog.

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.

publicApi: {
  path: "articles",
  fields: ["title", "slug", "excerpt", "featured", "category", "noIndex", "publishedAt"],
  searchableFields: ["title", "excerpt"],
  orderableFields: ["publishedAt", "title"],
  filterableFields: ["category", "featured"],
},

publicWriteCopy Anchor Link

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. Every option, route and error: Public write API.

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

A container field, such as board, may be in create.fields only. Moving a record to another container is a staff edit.

deliveryCopy Anchor Link

Gives each published record a public page: canonical URL, SEO metadata, redirects from old slugs and a sitemap. Guides: Public pages and SEO.

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.

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

editorialCopy Anchor Link

Adds a version column, revision history and the can_restore permission. liveEditing builds on it. Guide: Revisions, previews and scheduling.

editorial: {
  revisions: { retention: 20 },
  preview: { expiresInMinutes: 30 },
  scheduling: true,
},

localizationCopy Anchor Link

Creates a {tableName}_translations table for fields marked localized: true. Guide: Translate content.

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.

localization: {
  defaultLocale: "en",
  fallback: "default",
},

searchCopy Anchor Link

Keeps published records in the site search index. Drafts never show up in public results. Guide: Search.

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 add the locale prefix.

search: {
  titleField: "title",
  descriptionField: "excerpt",
  contentFields: ["title", "excerpt"],
  pathTemplate: "/articles/{slug}",
  authorField: "author",
},

visibilityCopy Anchor Link

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.

publication: true,
visibility: true,

reportsCopy Anchor Link

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. Render the public button with ReportButton and contentTarget(manifest.id, definition, record.id). Guide: Enable reports. Options and components: Moderation reference.

publicApi: { path: "blog", fields: ["id", "title", "friendlyUrl", "content"] },
reports: true,

threadCopy Anchor Link

Makes records of one content type answer each other under a root record, like forum comments under a topic. It adds the public GET /{path}/thread route and checks every placement on the server. Guide: Threaded replies.

thread: { parent: "parent", root: "topic", maxDepth: 6 },

Both fields must be in publicApi.fields and neither may be in publicWrite.update.fields. thread is not available on a localized content type yet.

duplicationCopy Anchor Link

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.

duplication: true,

idStrategyCopy Anchor Link

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.

Any other value throws. Changing the strategy of a content type that already has records needs a hand-written data migration.

idStrategy: "bigint",

indexesCopy Anchor Link

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.

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.

indexes: [{ on: ["syndication.priority"] }],

liveEditingCopy Anchor Link

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.

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 and AI actions.

Which options need whichCopy Anchor Link

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

Unique across content typesCopy Anchor Link

Plugin registration checks these across every installed content type: