Singles

A single is a one-off document — content that exists as exactly one instance. Site settings, navigation headers, footers, and homepage configurations are typical singles. Unlike collections, singles have no list view, no create/delete operations, and are auto-created on first access.

Source of truth: the SingleConfig interface lives in packages/nextly/src/singles/config/types.ts. The defineSingle() helper is in packages/nextly/src/singles/config/define-single.ts.

import {
  defineSingle,
  text,
  upload,
  group,
  repeater,
} from "nextly";

export default defineSingle({
  slug: "site-settings",
  label: { singular: "Site Settings" },
  admin: {
    group: "Settings",
    icon: "Settings",
    description: "Global site configuration",
  },
  fields: [
    text({ name: "siteName", required: true, label: "Site Name" }),
    text({ name: "tagline", label: "Tagline" }),
    upload({ name: "logo", relationTo: "media", label: "Logo" }),
    upload({ name: "favicon", relationTo: "media", label: "Favicon" }),
    group({
      name: "seo",
      label: "SEO Defaults",
      fields: [
        text({ name: "metaTitle", label: "Default Meta Title" }),
        text({ name: "metaDescription", label: "Default Meta Description" }),
      ],
    }),
    repeater({
      name: "socialLinks",
      label: "Social Links",
      fields: [
        text({ name: "platform", required: true }),
        text({ name: "url", required: true }),
      ],
    }),
  ],
  access: {
    read: true,
    update: ({ roles }) => roles.includes("admin"),
  },
  hooks: {
    afterChange: [
      async ({ doc }) => {
        await fetch("/api/revalidate?tag=site-settings", { method: "POST" });
      },
    ],
  },
});

import { defineConfig } from "nextly";
import SiteSettings from "./src/singles/site-settings";
import Header from "./src/singles/header";
import Footer from "./src/singles/footer";

export default defineConfig({
  singles: [SiteSettings, Header, Footer],
});

How singles differ from collections

Single options

Only slug and fields are required.

slug

Unique identifier across all singles and collections and components. Used as the API endpoint path and database table name (with the single_ prefix unless dbName is set). Must be lowercase and URL-friendly.

fields

Array of field definitions. Singles support the same field types as collections. See Fields.

label

Display label in the admin sidebar, breadcrumbs, and page titles. Singles only need a singular label since there is exactly one document.

dbName

Custom database table name.

description

Description displayed in the admin UI. Falls back to admin.description.

sanitize

When enabled, the global sanitization hook strips HTML tags from plain-text fields (text, textarea, email) before storage. Set to false only if the single intentionally stores HTML in those fields.

custom

Arbitrary metadata for hooks, plugins, or custom code. Not persisted to the database.

Admin options

Configure how the single appears in the admin panel via the admin property.

Singles do not support useAsTitle, pagination, preview, or admin-component overrides — those concepts are collection-specific.

Access control

Singles only support read and update — there is no create or delete since the document is auto-created on first access and cannot be removed.

access: {
  read: true,
  update: ({ roles }) => roles.includes("admin"),
}

Each operation accepts a function (returning boolean | Promise<boolean>), a literal boolean, or can be omitted to fall back to database role/permission checks. Code-defined access takes precedence; super-admin always bypasses checks. The AccessControlContext shape is the same as for collections.

Hooks

Singles support four lifecycle hooks — a subset of the eight available on collections.

Four available hooks

Execution order — read

1. beforeRead
2. Database read
3. afterRead

Execution order — update

1. beforeChange
2. Database update
3. afterChange

Example: cache invalidation

hooks: {
  afterChange: [
    async ({ doc }) => {
      // Invalidate ISR / CDN caches when settings change
      await fetch("/api/revalidate?tag=site-settings", { method: "POST" });
    },
  ],
  afterRead: [
    async ({ doc }) => {
      // Add a computed field
      return { ...doc, fullTitle: `${doc.siteName} - ${doc.tagline}` };
    },
  ],
}

When to use which hook

• beforeRead — modify query filters (e.g., scope to the current tenant), audit logging.
• afterRead — compute virtual properties, redact sensitive fields.
• beforeChange — coerce inputs and final mutations before the row is persisted.
• afterChange — cache busting, webhooks, queue jobs.

Throwing inside any hook aborts the operation and rolls back the transaction.

Example: header navigation

import { defineSingle, repeater, text, relationship } from "nextly";

export default defineSingle({
  slug: "header",
  label: { singular: "Header Navigation" },
  admin: {
    group: "Navigation",
    icon: "Menu",
  },
  fields: [
    repeater({
      name: "navItems",
      label: "Navigation Items",
      fields: [
        text({ name: "label", required: true }),
        text({ name: "url" }),
        relationship({ name: "page", relationTo: "pages" }),
      ],
    }),
  ],
  access: {
    read: true,
    update: ({ roles }) => roles.includes("admin") || roles.includes("editor"),
  },
});

Next steps

• Collections — content types with multiple entries
• Fields — every field type and validation option
• Components — reusable field groups for collections and singles
• Visual Schema Builder — create singles visually with drag-and-drop