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: ({ permissions }) => permissions.includes("site-settings:update"),
  },
  hooks: {
    afterChange: [
      async ({ data }) => {
        // Nextly invalidates its own cache tags on every write once the cache
        // revalidator is registered (see ISR caching). Use hooks for side
        // effects of your own.
        console.info("site settings updated", data);
      },
    ],
  },
});

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 field groups. 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: ({ permissions, collection }) =>
    permissions.includes(`${collection}:update`),
}

Each operation accepts a function (returning boolean | Promise<boolean>), a literal boolean, or can be omitted to fall back to database role/permission checks. A declared rule is what a signed-in user is judged by, so it checks the permission itself and narrows from there; don't decide by a role's name. 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.

Five available hooks

Execution order — read

1. beforeRead
2. Database read
3. afterRead

Execution order — update

1. beforeValidate
2. Validation - the schema's declared rules are enforced
3. beforeChange
4. Database update
5. afterChange

The validation gate is what separates the two write hooks. Use beforeValidate to supply or repair a value you want the rules applied to; use beforeChange to derive the value that gets stored, knowing the document has already passed them. What a beforeChange handler returns is written without being re-validated.

Example: cache invalidation

hooks: {
  afterChange: [
    async ({ data }) => {
      // Nextly's own cache tags are already invalidated on every write once
      // the cache revalidator is registered (see ISR caching). Notify a
      // system of your own here, with an absolute URL: a relative fetch
      // throws on the server.
      await fetch(`${process.env.NEXT_PUBLIC_APP_URL}/api/my-webhook`, {
        method: "POST",
        body: JSON.stringify(data),
      });
    },
  ],
  afterRead: [
    async ({ data }) => {
      // Add a computed field
      return { ...data, fullTitle: `${data.siteName} - ${data.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.
• beforeValidate — coerce inputs (trim strings, normalize casing), or supply a value the rules require.
• beforeChange — final mutations before the row is persisted, on data already known to be valid.
• 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: ({ permissions }) => permissions.includes("header:update"),
  },
});

Next steps

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