agntcms-sections

agntcms Section Creation

Creating a section is exactly two operations. Both are required. Partial state — a folder without a config entry, or a config entry without a folder — is invalid and will either be invisible to the framework or cause a compile-time import error.

---

Step 1: Create the section folder

Create agntcms/sections/<SectionName>/ and populate it with the following files.

index.ts (required)

The entry point for the section. Calls defineSection and exports the SectionDefinition.

import { defineSection, TextField, ImageField } from '@agntcms/next'
import { Hero } from './component'

export const HeroSection = defineSection({
  name: 'Hero',
  category: 'Hero',
  schema: { title: TextField, image: ImageField },
  component: Hero,
})

The name value ('Hero') is the string that content JSON uses in the type field. It must be unique across all registered sections. Choose it carefully — renaming it later requires a migration of all content files that reference the old name.

category is optional but should always be set. It groups sections in the picker modal. Canonical values used by the template: 'Hero', 'Content', 'CTA', 'Features', 'Social Proof', 'Forms', 'Layout', 'Global'. Any string is valid — these are just the established conventions. See agntcms-section-new for the full list and guidance.

component.tsx (required)

The React component that renders the section. Props must match the schema exactly — TypeScript will catch mismatches at compile time. Use EditableText, EditableImage, and other <EditableX> components from @agntcms/next/client so fields are inline-editable through the live UI. Since v0.2, Props use EditableSlot<K, V> instead of raw value types — this means rendering a field as {title} directly in JSX is a compile error. The type system enforces that every editable field is passed to an <EditableX> wrapper.

For LinkField fields, EditableLink renders only the label text; wrap it in an <a> element in the section component (the section controls href and target/rel, the editor controls the label). Use read(slot) from @agntcms/next/client to unwrap the slot to a bare LinkValue for use with hrefOf(). See agntcms-section-new for the full pattern.