Next.js CMS: Choosing Between Git, Headless, and Something You Already Have

The Next.js CMS question has three real answers, and they differ in who edits the content and where it lives: markdown in your git repository, a hosted headless CMS with an API, or a traditional CMS like WordPress used purely as a content API. Everything else is a variation on one of those.

Most comparison articles list a dozen products and rank them, which skips the decision that actually matters. The products within each category are more alike than different; the categories are genuinely different in who can edit, what happens when the service is down, and how much of your architecture depends on somebody else’s uptime. Pick the category first.

Table of contents

• Option one: content in the repository
• Option two: a headless CMS
• Option three: a traditional CMS, used headlessly
• How the rendering strategy interacts
• Preview, which is where implementations get messy
• A decision rule
• How this fits the rest of the stack
• FAQ

Option one: content in the repository

Markdown or MDX files committed alongside the code, read at build time. No external service, no API, no runtime dependency.

content/
  posts/
    building-a-cms.mdx
    choosing-a-database.mdx
app/
  blog/[slug]/page.tsx

Where it wins: the content is in version control with full history and code review. Builds are fully reproducible. There is no service to pay for, no API to rate limit, and no outage that takes your content offline. Preview is your existing pull request workflow. For a developer-authored blog or documentation site, this is very hard to beat.

Where it fails: non-technical editors. Asking a marketing colleague to clone a repository, edit frontmatter, and open a pull request is a real cost, and dressing it up as a workflow does not change that. Git-backed editing interfaces exist and help, but they are a layer over a model that was not designed for this.

It also means every content change triggers a rebuild. On a site with a hundred pages that is seconds. On one with fifty thousand it is a real constraint, and incremental static regeneration becomes necessary rather than optional.

Option two: a headless CMS

Content lives in a hosted service with a structured schema and an editing interface. Your Next.js app fetches it over an API at build time, at request time, or on revalidation.

Where it wins: editors get a real interface with structured fields, media handling, roles, scheduling, and preview. Content changes do not require a deploy. Multiple sites can consume the same content. For anything with a content team, this is the category.

Where it costs: you are now dependent on a third party for a core part of your application, with API rate limits, a pricing model that scales with usage, and a schema in somebody else’s system. Local development needs either a connection to the live service or a mocking layer. Portability is genuinely limited — content models rarely translate cleanly between products.

The question to ask during evaluation is the boring one: how do I export everything, in what format, and has anyone done it? A CMS you can leave is a CMS you can commit to.

There is a meaningful split inside this category between services you host and services somebody hosts for you. A self-hostable headless CMS gives you the editing interface without the third-party dependency, at the cost of running it — which is a database, a file store, and an upgrade path you own.

Option three: a traditional CMS, used headlessly

WordPress with its REST API or GraphQL, feeding a Next.js front end. Widely deployed and frequently dismissed unfairly.

Where it wins: the editing experience is one that millions of people already know, which removes a training cost entirely. The plugin ecosystem covers forms, SEO fields, media, multilingual, and custom fields without building any of it. If content already lives in WordPress, this is a front-end project rather than a migration.

Where it costs: you are running two systems. WordPress needs PHP, MySQL, updates, and security attention even though nobody visits it directly. The API is not as ergonomic as a purpose-built headless product, and getting exactly the fields you want often means a custom fields plugin plus API extensions.

The pragmatic case for this is stronger than its reputation suggests. A business already running WordPress, with editors who know it and a plugin set that works, gets a fast modern front end without asking anyone to relearn their job. That is a good trade, and the alternative — a six-month content migration to a product with a nicer API — frequently is not.

How the rendering strategy interacts

The CMS choice and the rendering strategy are coupled more tightly than people expect.

// static at build, revalidated on a timer
export const revalidate = 3600;

// on-demand revalidation from a CMS webhook
// app/api/revalidate/route.ts
import { revalidatePath } from 'next/cache';

export async function POST(request: Request) {
  const secret = request.headers.get('x-revalidate-secret');
  if (secret !== process.env.REVALIDATE_SECRET) {
    return new Response('Unauthorized', { status: 401 });
  }
  const { path } = await request.json();
  revalidatePath(path);
  return Response.json({ revalidated: true });
}

On-demand revalidation is the pattern worth building for any API-based CMS. The CMS fires a webhook when content is published, your route revalidates the affected path, and the page updates within seconds without a full rebuild. It is the combination that makes headless practical at scale.

Two details that bite. First, verify the webhook — an unauthenticated revalidation endpoint is a free cache-invalidation attack. Second, revalidate the paths that changed rather than the whole site, or you have rebuilt everything to publish one typo fix.

For git-based content, none of this applies: a push triggers a build, and that is the whole mechanism.

Preview, which is where implementations get messy

Editors need to see unpublished content before it goes live, and this is consistently the fiddliest part of a headless setup.

Next.js provides draft mode, which sets a cookie causing your data fetching to request draft content instead of published:

import { draftMode } from 'next/headers';

export default async function Page({ params }) {
  const { isEnabled } = await draftMode();
  const post = await getPost(params.slug, { preview: isEnabled });
  return <Article post={post} />;
}

The plumbing behind that — a route that validates a token from the CMS, enables draft mode, and redirects to the right page — is more work than the documentation implies, and it needs testing whenever either side upgrades.

Worth weighing during evaluation. A CMS with a well-documented Next.js preview integration saves days over one where you build it. And with git-based content, preview is your pull request deploy, which is one of that model’s quiet advantages.

A decision rule

• Developer-authored blog or docs, no non-technical editors — markdown in the repository. Simplest, cheapest, most durable.
• Content team, structured content, multiple channels — a headless CMS. This is what the category exists for.
• Content already in WordPress with editors who know it — WordPress headless. Do not migrate a working content operation to get a nicer API.
• Compliance or data residency constraints — a self-hosted CMS, headless or traditional.
• Genuinely unsure — start with markdown. Moving from markdown to a CMS later is straightforward, because your content is in a portable format and you own it. Moving off a proprietary CMS is not.

That last point is the one worth weighting heavily. The reversible choice is usually the right first choice, and content in files is about as reversible as it gets.

How this fits the rest of the stack

Whichever category you pick, the Next.js application itself is the piece that needs building on push, serving on a live route, and rolling back when a content model change breaks a template. Next.js applications deploy from a GitHub repository on RunxBuild with build logs, environment variables for API tokens, custom domains, and rollback to the previous deploy — and if the headless option you choose is a self-hosted CMS with a database, that can sit beside it as a managed MySQL or Postgres rather than a separate account. Deploying from GitHub on RunxBuild covers the repository connection, and the RunxBuild hosting calculator shows the front end, any backend service, the database, and bandwidth as separate figures.

Useful related references:

• Static Site CMS: The Git-Based, the API-Based, and the One That Beats Both for Most Teams
• Next.js Middleware: What Belongs In It and What Will Bite You
• Vite vs Next.js: Picking Without the Framework Argument
• Services on RunxBuild

FAQ

What is the best CMS for Next.js?

It depends on who edits the content. For developer-authored blogs and docs, markdown in the repository is hard to beat. For a content team needing structured fields and scheduling, a headless CMS. If content already lives in WordPress with editors who know it, WordPress used headlessly is a pragmatic choice.

Should I use a headless CMS or markdown files?

Markdown wins on simplicity, version control, reproducible builds, and zero external dependencies — but it requires technical editors. A headless CMS wins on editorial experience and lets content change without a deploy, at the cost of a third-party dependency and limited portability.

Can I use WordPress as a CMS for Next.js?

Yes, through its REST API or GraphQL. The advantage is an editing interface your team already knows plus a plugin ecosystem covering SEO fields, media, and custom fields. The cost is running two systems, since WordPress still needs PHP, MySQL, and security updates even though nobody visits it directly.

How do I update a Next.js page when CMS content changes?

Use on-demand revalidation: the CMS fires a webhook on publish, and a route handler calls revalidatePath for the affected paths. Verify the webhook with a shared secret, and revalidate only the changed paths rather than the whole site.

How does preview work with a headless CMS in Next.js?

Through draft mode — a route validates a token from the CMS, enables draft mode via a cookie, and redirects to the page, where your fetch requests draft rather than published content. The plumbing is more involved than it looks, so a CMS with a documented Next.js preview integration saves real time.