Globals

Define single documents such as site settings with global().

On this page

This page shows how to define a global, a single document that is not part of a collection, and how to read and update it.

Use a global for content that exists once: site settings, navigation, a footer.

src/kitcms.config.ts
import { defineConfig, fields as f, global } from '@kitcms/core';

const site = global({
	slug: 'site',
	label: 'Site settings',
	versions: { drafts: true },
	access: { read: () => true },
	fields: {
		siteName: f.text({ required: true }),
		tagline: f.textarea(),
		nav: f.array({
			fields: {
				label: f.text({ required: true }),
				href: f.text({ required: true }),
			},
		}),
	},
});

export default defineConfig({ collections: [], globals: [site] });

Options

Option What it does
slug Lowercase letters, digits, - and _. Unique among globals. Required.
fields The fields, as in a collection. Required.
label Admin label. Default: derived from the slug (site-settings becomes Site settings).
admin { description?, group?, hidden? }.
access { read, update }. Rules return booleans only. Default: signed-in users only.
hooks The collection hooks without the delete hooks.
versions History and drafts, as on collections. See Drafts and versions.
entitlement Gates the global behind an add-on.

Each global is stored in one single-row table named _global_<slug>, and runs through the same pipeline as a collection.

Read and update

const site = await locals.cms.findGlobal('site');
await locals.cms.updateGlobal('site', { tagline: 'Hello' });

findGlobal never returns null. A global that was never saved returns its default values. updateGlobal creates the row on the first save. createdAt and updatedAt are missing until then.

In the admin, globals appear in the navigation and open at /admin/globals/<slug>.

Over RPC, use findGlobal for reads, and updateGlobal with { as: 'system' } for writes. Over REST, use GET and PATCH on /api/globals/:slug.

Edit this page on GitHub