KadraGuides

Common bugs in a Node.js CMS backend, and how to fix them

A content management system looks simple: posts go in and posts come out. Most of its bugs are about state, like when a post last changed or who is allowed to see it. This guide walks through the ones that come up most in a Node.js or TypeScript CMS, with examples from Quillio, Kadra's headless CMS practice codebase.

Updated

Every write path has to update the timestamp

Feeds sort by updatedAt so recently changed posts rise to the top. If creating a post sets it but publishing and editing don't, the feed looks frozen while authors keep working. That's Quillio's CMS-401 ticket.

When you fix it, check every function that writes a post, not just the one named in the bug report. And pass the current time in as an argument instead of calling Date.now() deep inside, so a test can pin the clock:

// The caller decides what "now" is, so a test can control it
export function rename(post: Post, title: string, now: number): Post {
  return { ...post, title, updatedAt: now };
}

// in a test
expect(rename(post, "New title", 1_700_000_000_000).updatedAt).toBe(1_700_000_000_000);

Slugs have to be unique, ignoring case

A slug is the readable part of a post's URL, like /posts/hello-world. If two posts share one, whichever the router finds first wins and the other one vanishes. Quillio's CMS-408 ticket is a create path that never checks. The check also has to ignore case, because My-Post and my-post look like the same URL to a reader.

Check in code so you can return a clear error, and back it with a unique index in the database. Two requests that arrive at the same moment can both pass the code check, and only the index stops the second insert:

CREATE UNIQUE INDEX posts_slug_lower_idx ON posts (lower(slug));

Then decide what the API does on a collision. It can reject the request with a 409, or add a suffix like hello-world-2. Either is fine as long as it's documented and tested.

Drafts must never reach the public API

A draft is unfinished work, and sometimes it holds news that isn't public yet. If the public endpoints don't filter on status, anyone can read drafts by guessing a slug or an id. In Quillio that's CMS-417, the senior ticket of the sprint.

The usual mistake is fixing the list endpoint and forgetting the detail endpoint, which looks a post up by slug or id. Put the visibility rule in one function that both endpoints call, then test each of these:

  • The public list leaves drafts out.
  • The public detail endpoint returns not found for a draft, the same answer it gives for a post that doesn't exist, so it doesn't reveal that the draft is there.
  • The authoring endpoint still shows authors their own drafts.

Turn each acceptance criterion into a test

Each of these tickets comes with acceptance criteria, and each criterion becomes a test. Include the ones about what must not change, like untouched posts keeping their place in the feed. Those catch the regressions a reviewer looks for first.

Practice on a working CMS

Quillio is a TypeScript headless CMS on Node with the CMS tickets above planted in it. You get your own GitHub repo, fix each ticket on a branch named after it, and open a pull request. An AI teammate reviews the diff, and a hidden Vitest suite decides whether the fix passes.

Every Quillio repo opens in GitHub Codespaces with Node and npm installed, so there's nothing to set up locally.

Questions people ask

What is a slug in a CMS?

The human-readable part of a post's URL, usually made from its title, like hello-world in /posts/hello-world. It has to be unique so each URL points to exactly one post.

Should I enforce unique slugs in code or in the database?

Both. The code check gives the user a clear error message. The database index is what actually guarantees uniqueness, because two requests at the same moment can both pass a check in code.

What does a junior developer work on in a CMS team?

Mostly small changes in code that already exists, such as a field that isn't saved or a list that sorts wrong. The skill is finding the right place to change and proving the fix with a test.

Is Kadra free?

Yes, Kadra is free during beta with no credit card. After beta, Pro is planned at $12 a month or $79 a year, and the demo and your first full sprint stay free.

Try it on a real ticket

Pick a stack, fix a bug in a working codebase and get your pull request reviewed. Free during beta.

More guides