cms-lab
Docs / Large catalogs

Large catalog scanning

Large CMS projects need a baseline before they need a hard gate. Start with focused scans, tune route probing, then decide which checks should block deploys.

Build a first baseline

For catalogs with thousands of entries, do not start with the strictest CI command. Write a report first, review the noisy content types, and only then raise thresholds.

npx @cms-lab/cli doctor
npx @cms-lab/cli scan --report --markdown --fail-on never

Narrow the scope

Use --type when one collection is the deploy risk. Use --only when you need a focused pass on route reachability, fields, SEO, or image checks.

npx @cms-lab/cli scan --type menu_item --only routes
npx @cms-lab/cli scan --type branch --type category --only fields,seo
npx @cms-lab/cli scan --skip images --fail-on never

Tune route probes

The default concurrency is conservative. Increase it only when your local app, staging site, and CMS can handle the load. Increase timeout when the app renders slow pages. Use retries for transient 5xx or network failures, not for deterministic broken routes.

npx @cms-lab/cli scan --concurrency 4 --timeout 10000 --retries 2
npx @cms-lab/cli scan --type product --concurrency 12 --only routes

Local scans versus CI scans

Local scans can be broad because a developer is watching the report. CI scans should start with critical content types and known deploy risks. Once the baseline is clean, tighten the failure threshold.

npx @cms-lab/cli scan --ci --type menu_item --only routes --report --fail-on error
npx @cms-lab/cli scan --ci --type page --only fields,seo --max-warnings 0

Outputs for large results

  • Use --report for human review and filtering.
  • Use --markdown for release notes or PR summaries.
  • Use --junit when CI should display failures as test results.
  • Use --json for custom scripts or annotations.
  • Keep --include-sensitive-output off unless the output stays private.

Current limits

cms-lab can narrow, probe, and report large route and field-check workflows. It does not yet implement deep cross-document business rules such as "every active menu item must have one pricing record per branch." Track those as custom relationship checks rather than treating basic route scanning as proof of relational correctness.

Next steps: scan command, adapter maturity, and troubleshooting.