CMS

Checks

A check is a function on your server that looks at a doc and reports whether it's ready, e.g. that it has SEO metadata or that every string is translated. Editors can run checks on demand from the doc editor, and a collection can require them to pass before its docs are published.

Checks are in beta, so their interface may change between versions.

Defining a check

Register checks with the checks option of cmsPlugin(). Each one has an id, a label and a run() function that returns a status of success, warning or error, with a message in Markdown:

// @/root.config.ts

import {defineConfig} from '@blinkk/root';
import {cmsPlugin, translationsCheck} from '@blinkk/root-cms/plugin';

export default defineConfig({
  plugins: [
    cmsPlugin({
      // ...
      checks: [
        translationsCheck(),
        {
          id: 'seo-meta',
          label: 'SEO metadata',
          description: 'Checks that the doc has a meta title and description.',
          collections: ['Pages', 'BlogPosts'],
          run: async (ctx) => {
            const doc = await ctx.cmsClient.getRawDoc(
              ctx.collectionId,
              ctx.slug,
              {mode: 'draft'}
            );
            const meta = doc?.fields?.meta || {};
            if (!meta.title || !meta.description) {
              return {
                status: 'error',
                message: 'Add a `meta.title` and `meta.description`.',
              };
            }
            return {status: 'success', message: 'All good!'};
          },
        },
      ],
    }),
  ],
});

The ctx passed to run() has the docId, collectionId and slug of the doc being checked, its collectionSchema, the rootConfig and a cmsClient for reading content. Checks run on the server, so they can also call internal services or APIs that need credentials.

collections limits a check to docs in those collections. Without it, the check applies to every collection.

Running checks in the editor

When a project has checks, the doc editor's status bar shows a Checks button. It opens a panel that lists the checks for the doc's collection, and editors can run each one against the current draft and read its message.

Gating publishing

To run checks as part of publishing, list them under publishing.checks in a collection's schema. Each entry is a check id or an {id, level} object:

// @/collections/Pages.schema.ts

import {schema} from '@blinkk/root-cms';

export default schema.collection({
  name: 'Pages',
  url: '/[...slug]',
  publishing: {
    checks: [
      // A bare id is a required check.
      'seo-meta',
      {id: 'root-cms/translations', level: 'warning'},
    ],
  },
  fields: [
    // ...
  ],
});

A required check (the default) stops publishing when it returns an error. A warning check never stops publishing; its message is shown once the content is live, and an error from it is treated as a warning. The same check can be required in one collection and a warning in another.

Checks run when a doc is published or scheduled, and when a release is published or scheduled, where a failed required check on any of its docs stops the whole release. Scheduled content is checked when it is scheduled, not again when it goes live.

Admins can skip the checks, or publish anyway after a required check fails. Publishing writes go straight from the browser to Firestore, so checks are a workflow guardrail rather than a security boundary. Every publish records what the checks did, including skips and overrides, in the action's metadata. A check that throws is reported as an error for that check only, and a check id that isn't registered is skipped.

Missing translations

translationsCheck() is a built-in check with the id root-cms/translations. It finds the doc's translatable strings (fields with translate: true) and reports any that are missing a translation for one of the doc's enabled locales. Pass {collections: ['Pages']} to limit it to some collections.