Next.js boilerplate with MDX blog

Every post needs frontmatter, and it has to validate

src/lib/blog/frontmatter.ts is the contract. A file that does not satisfy it fails the build, not the review:

• title: required, under 70 characters.
• description: required, 50 to 160 characters. It is the meta description, the blog-index excerpt and the RSS <description>. "TODO" is not a description, and neither is the first sentence of the post copied verbatim.
• date: required, quoted, ISO YYYY-MM-DD. Quote it or YAML turns it into a Date and the type check fails.
• tags: optional, lowercase and hyphenated (edge-runtime, not Edge Runtime). Reuse an existing tag before inventing one; check allTags().
• author: optional string.
• draft: optional boolean. true hides the post from the index, the feed and the sitemap in production, while leaving it visible on the dev server.

Never read the clock to fill in date. The publication date is a fact about the post that a human decides; a generated new Date() makes every rebuild produce a different sitemap and feed.

The filename is the URL, and it is permanent

content/blog/scaling-postgres.mdx publishes at /blog/scaling-postgres.

• Filenames are lowercase and hyphenated. The loader rejects anything else.
• Once a post is deployed, its slug is immutable. Rewrite the title as often as you like; renaming the file breaks every inbound link, every share and the <guid> in the feed that readers' RSS clients use to tell posts apart.
• If a slug genuinely has to change, it is a new file plus a redirect in next.config.ts from the old path, never a silent rename.
• One post per file. Do not add a second post's frontmatter to an existing file.

Body rules

• Start with the problem, not with a preamble about what the post will cover.
• Code blocks must be complete enough to paste and run. No ... inside a function body, no imports left implicit.
• Use ## and ### for structure. rehype-slug turns each into an anchor people link to, so treat a published heading as an address: reword it only when the content underneath genuinely changed.
• Images go in public/blog/<slug>/ and are referenced as /blog/<slug>/x.png. Size and compress them before committing; there is no image pipeline here.
• Only components registered in src/mdx-components.tsx are available. Do not add an import of a client component to a post to get around that: register it once, deliberately, and use it everywhere.

Before you call a post done

bun run blog:check
bun run build

The first validates the frontmatter of every post at once; the second proves the MDX compiles and the OG image renders.

No MDX compiler at runtime

• Post bodies are compiled by the bundler through the dynamic import() in src/app/blog/[slug]/page.tsx. Do not replace it with a runtime compiler (next-mdx-remote, @mdx-js/mdx's evaluate, compile() in a route handler). Those pull the full MDX toolchain into the server bundle and turn a static page into per-request work.
• generateStaticParams plus export const dynamicParams = false is what makes every post prerendered and every unknown slug a 404. Keep both.
• src/lib/blog/posts.ts uses node:fs and is server-only. Importing it from a client component (anything with "use client" at the top, directly or transitively) breaks the build. Pass the data down as props instead.

Colours come from tokens, in the component map too

• Every element mapping in src/mdx-components.tsx and every component in src/components/blog/ uses design-token utilities: text-ink, text-body, text-muted, bg-surface-card, border-hairline, rounded-md, the text-title-* and text-body-* type scale, and the p-*/gap-* spacing scale.
• No Tailwind palette classes, no hex literals, no inline style colours. A post must restyle itself when the design plugin changes, and a raw colour in the MDX map is the one thing that survives that change and looks wrong.
• The single exception is opengraph-image.tsx: Satori understands inline styles only. Keep it to two colours and keep them in step with the tokens in src/app/globals.css.

Metadata is not optional

• Every post page exports generateMetadata with a title, the frontmatter description, a canonical URL and Open Graph fields. Missing metadata is a missing rich preview and a duplicate-content risk.
• Canonical URLs, feed links and sitemap entries are built from appUrl() (NEXT_PUBLIC_APP_URL). Never hardcode a domain and never build one from request headers: a canonical tag pointing at a preview deployment deindexes the real page.
• The per-post opengraph-image.tsx is what puts og:image in the head. Do not also set openGraph.images by hand; you will end up with two, and consumers pick the wrong one.

Feeds and sitemaps are deterministic

• lastModified and pubDate come from frontmatter (updated ?? date), never from Date.now(). A sitemap whose dates change on every deploy trains crawlers to ignore its dates.
• Escape everything that goes into XML. escapeXml in the feed route exists because one ampersand in a title makes the whole feed invalid.
• Posts are sorted newest first with the slug as the tiebreaker, so two posts published on the same day do not swap places between builds.