cms-lab documentation

cms-lab is a local CLI for checking the contract between headless CMS content and a Next.js site. It runs from your project, fetches CMS documents, probes expected routes, and produces terminal, JSON, or a local HTML report.

Choose a path

I have a Next.js frontend and want to scan routes

Start your app, write the config, run doctor, then run the scan command.

Scan command

I only have a CMS/backend right now

Generate agent context and document route assumptions before the frontend exists.

Backend-only workflow

I use Directus, Strapi, or another relational CMS

Check adapter maturity first, then model route mappings and required fields explicitly.

Adapter maturity matrix

I have thousands of CMS entries

Start with a baseline, narrow by content type, and tune route probe concurrency before making CI strict.

Large catalog scanning

I want CI output

Run cms-lab after the app is serving and upload the local report as a private artifact.

CI setup

I want AI/coding-agent context

Generate safe project context files for tools that need CMS and route information.

Agent context

I need to understand a first scan

Read the diagnostic codes and compare the output with common CMS failure examples.

Diagnostics

Something failed before the scan ran

Check common setup errors such as missing config, unreachable CMS, or a site health route that points at the wrong page.

Troubleshooting

How it works

The config declares your site URL, framework, CMS repository, route mappings, and optional required fields. The scanner loads CMS documents, resolves each expected path, checks the running site, then adds content diagnostics for SEO, images, UID, and required field gaps. Provider adapters keep the original CMS payload while normalizing stable IDs, UID-like slugs, status, and public URLs where the CMS exposes them.

Scopecms-lab supports Next.js App Router and Pages Router with Prismic, Strapi, Directus, WordPress, Contentful, and Sanity adapters. Shopify, internal links, and schema drift checks stay out of the default scan until they have adapters, fixtures, and release smoke coverage.

Install

Run without installing:

npx @cms-lab/cli scan

Or pin it in a project:

pnpm add -D @cms-lab/cli @cms-lab/core

Your first scan

Start your Next app, create a config file, then run scan. Use doctor first when connecting a repo for the first time.

first run

$ npx @cms-lab/cli doctor
config ok - cms-lab.config.ts
next app ok - app
site ok - http://localhost:3000
cms ok - 6 documents

$ npx @cms-lab/cli scan --report

If you only have a CMS/backend

Start with config and agent context. Route scans wait until a frontend is running, but backend-only projects can still document collection shapes, route plans, and field assumptions for coding agents.

Read the backend-only workflow

Try a runnable example

If you want to see cms-lab before wiring it into your own CMS, open the broken Prismic demo in a browser workspace. It intentionally produces a report with real route, field, SEO, and image diagnostics.

Run in StackBlitz

How it fits with other tools

cms-lab does not replace Playwright, Lighthouse CI, accessibility tools, or link checkers. It covers the CMS-aware layer between content records and routes.

Read the comparison guide

Project stability

cms-lab is early, so the docs separate stable CLI behavior from adapter maturity and planned checks. Review the versioning policy before using a scan as a deploy gate.

Read the versioning policy

Where to next

Have a question or an idea for a check or adapter? Open a discussion, or see what is planned on the roadmap.