DEV Community

i-afaqrashid
i-afaqrashid

Posted on

Catching CMS bugs before deploy in Next.js

#nextjs #cms #webdev #opensource

Your Next.js build is green. Types pass. Lighthouse is fine. Then a customer emails: a product page is 404ing. An editor unpublished the linked brand doc last week. Nobody noticed, because nothing in CI looks at the gap between your CMS content and your routes.

This is the quiet failure mode of headless CMS plus Next.js: the CMS and the route layer drift apart over time. Common versions:

  • An editor renames a slug, so the old route 404s and the new one isn't generated yet.
  • A page is published but the content it references is still a draft, so the live page links to nothing.
  • Two documents resolve to the same path; only one wins at runtime.
  • The OG image, canonical, or JSON-LD is blank or malformed, so shares and search results break silently.
  • A page exists in en but not fr, so the locale switcher dead-ends.

None of these break the build. They break production.

I built cms-lab to catch this class of bug in CI. It fetches your CMS content, resolves your configured routes, probes the running site, and fails on real problems:

npx @cms-lab/cli scan
Enter fullscreen mode Exit fullscreen mode

It supports Prismic, Strapi, Directus, WordPress, Contentful, Sanity, and Payload, and runs as a CLI or a GitHub Action. Checks that can be noisy (canonical, OG, JSON-LD, image dimensions) are off by default, so a first run on a real project surfaces signal, not noise.

A minimal config maps content types to routes:

import { defineConfig } from "@cms-lab/core";

export default defineConfig({
  site: { url: "http://localhost:3000" },
  framework: { type: "next", router: "app" },
  cms: {
    provider: "payload",
    url: "http://localhost:3000",
    collections: [{ type: "page", collection: "pages", uidField: "slug" }],
  },
  routes: [{ type: "page", pattern: "/:slug", getPath: (doc) => `/${doc.uid}` }],
});
Enter fullscreen mode Exit fullscreen mode

In CI it returns a non-zero exit code when something is wrong, so a broken route or missing metadata blocks the deploy instead of reaching users.

It is new and open source (MIT). If you run Next.js on a headless CMS, I would like to know whether these checks match bugs you have actually hit, and which adapter or check is missing: https://github.com/i-afaqrashid/cms-lab

Top comments (0)