cms-lab

CLI for catching CMS-driven Next.js failures before deploy.

npx @cms-lab/cli scan

Commands

cms-lab init
cms-lab init --cms strapi --router pages
cms-lab init --cms directus --router pages
cms-lab doctor
cms-lab doctor --debug --verbose 2
cms-lab scan --report
cms-lab scan --report --share-report
cms-lab scan --markdown
cms-lab scan --junit
cms-lab scan --slack-webhook "$CMS_LAB_SLACK_WEBHOOK"
cms-lab scan --debug
cms-lab scan --json
cms-lab scan --json --include-sensitive-output
cms-lab scan --max-warnings 0
cms-lab scan --strict
cms-lab agent-context
cms-lab agent-context --mode cms-only
cms-lab agent-context --preset all
cms-lab agent-context --preset claude
cms-lab agent-context --preset gemini
cms-lab agent-context --preset copilot
cms-lab agent-context --force
cms-lab explain CMS-ROUTE-404

Scope

cms-lab supports Next.js App Router and Pages Router projects using Prismic, Strapi, Directus, WordPress, Contentful, and Sanity. It validates configured CMS route mappings, route reachability, UID gaps, SEO metadata, image alt text, and project-specific required fields and relationship minimums.

cms-lab init --cms strapi --router pages writes a Strapi starter config with collections, single types, route examples, and the Strapi relation route helper. cms-lab init --cms directus --router pages writes a Directus starter config with branch, menu item, category, and non-routable pricing collection examples. Use site.healthPath or site.healthUrl in config when the app root is not the right page for the initial health probe.

Debug logs use stderr and support --debug plus --verbose <0|1|2|3>, so JSON scan output remains clean on stdout. Raw CMS document data is redacted from --json output, along with document URLs, UIDs, and absolute project paths, unless --include-sensitive-output is passed explicitly.

CI strictness can be raised with --fail-on warning, --max-warnings <count>, --max-info <count>, or --strict.

Exports include local HTML (--report), share-safe local HTML (--report --share-report), Markdown (--markdown), JUnit XML (--junit), and redacted Slack incoming webhook summaries (--slack-webhook <url>). Terminal, JSON, Markdown, and HTML outputs include repeated-finding summaries when many documents hit the same content type/template issue. Share-safe HTML redacts CMS source IDs and local project paths while keeping diagnostic codes, severity, route paths, and field paths visible. Slack notifications send counts and diagnostic codes only, never raw CMS payloads, local paths, or webhook URLs.

cms-lab agent-context writes safe handoff files so coding agents can read the cms-lab docs, package links, route mappings, and safe project facts before attempting fixes. The default preset writes AGENTS.md plus shared files in .cms-lab/. Tool-specific presets can write CLAUDE.md, GEMINI.md, Copilot instructions, and a reusable Copilot prompt. Existing files are not overwritten unless --force is passed. Use --mode cms-only in backend-only CMS projects; the generated context will state that no frontend was detected and that route scans need a running app.

Config

Create cms-lab.config.ts in the target Next.js project. Import defineConfig from @cms-lab/core.

See the repository README for full setup, CI, and live Prismic testing.

Release History

See the repository changelog and GitHub Releases for version-by-version notes.

Open Source

MIT licensed. See the repository license, contributing guide, and support guide.