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, localization and search take an options object. publication and liveEditing are true, and editorial and delivery 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 and editorial adds can_restore.

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 and blocks. A file is returned as its public descriptor, never as the file 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.

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

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

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: