I had no system. I had vibes.

Then I ran the audit that wiped the registry.

The system I wanted

I wanted four content pillars, four primary niches that described the shape of my blog. Every published post had to declare a pillar. Tags had to map to pillars. A build-time validator had to fail if a published post declared a pillar that no tag supported.

Four pillars:

• ai — AI tooling, agents, OpenCode, Claude Code, agentic coding workflows
• homelab — self-hosting, hardware, Unraid, servers, OS setup on machines
• rabbit-holes — broad technical pillar: shipping projects + debugging/learning while building things
• reflections — non-tech, opinion, career, expanded thoughts

The pillars themselves were the easy part.

The hard part was the tags.

The audit

I ran the audit as a wayfinder pass. One decision per tag.

The mechanics were dull. Every tag lives in a post's frontmatter, so I pulled the frontmatter from all 41 posts, listed every tag with its count, and sorted by that. The agent did the tallying. The judgment calls were all mine.

Some tags were obviously load-bearing. projex showed up on every post that mentioned my component library. velite showed up on every post about my content pipeline. homelab showed up on the server posts. github showed up on the recovery and the deprecation posts.

Some tags were obviously decorative. debugging showed up on three posts, all of which were about different kinds of debugging. workflow showed up on five posts, all of which were about different kinds of workflows. ai-assisted-development showed up on one post.

The first rule was: if it recurs, keep it. That got me a first registry with about 48 tags in it, more than the posts actually used. Some were categories I wanted to exist rather than categories I had. It took reading the five workflow posts back to back to see the problem: they had nothing in common. The rule was measuring the wrong thing.

A tag earns its place if there's evidence of a series. At least one other post has to anchor it. A tag that could be folded into a broader existing tag gets folded. A tag that's used once and not part of a series dies. The count gets a hearing, but the posts have to actually belong together.

apt died. Used once. Subsumed by ubuntu. No reason to keep it.

github stayed. Multiple posts: the Ubuntu apt deprecation post and the git corruption recovery post. A real series about GitHub-shaped problems.

workflow died. Five uses, zero series. The tag was a context label, not a topic.

claude-code stayed. Two posts already, more coming. Real series.

The death rate was high. Of 41 tags that appeared across the 41 posts (the equal counts were an accident), 30 died. 11 survived.

The 11:

• ai: opencode, hermes, claude-code
• homelab: docker, zerowork, obsidian
• rabbit-holes: projex, velite, nextjs, github, ubuntu

(The registry also carries the pillar names themselves as tags: ai, homelab, reflections. Those aren't series. They're just the pillars.)

Yes, I could tag any post with the bare pillar name and the validator would wave it through. The validator catches accidents. The coherent-series test is what catches lies. Tagging a post reflections just to get through a build is workflow all over again.

reflections is the only pillar with no series tags. The first genuinely reflective post has to bring its tag through the PR process.

Why the death rate was the point

A tag is a promise. When I tag a post workflow, if you click this tag, you'll find a series of posts about workflows. The reader lands on a tag page expecting a coherent collection.

If the tag delivers three posts about three different things, the tag lied. Anyone who clicked it got a pile of nothing. That's on me.

I keep going back and forth on whether the test is too strict. It's not, really. A tag with no series is just noise on a tag page.

The 30 tags that died weren't wrong. They were over-promised. They were:

• context labels (debugging, thinking, meta, lessons-learned, retrospective, burnout)
• aspect descriptions (css, styling, build-time, production, ai-assisted-development)
• single-use nouns (apt, devto, router) that fit better as a broader existing tag

The 11 that survived are the tags I actually write in.

What the validator actually does

The build-time validator lives in velite.config.js, the config for Velite, my content pipeline. It runs on every build, for anything published. It checks: the declared pillar of a post must equal the pillar of at least one tag in tags[]. If it doesn't, the build fails.

This sounds bureaucratic. It isn't. It's the way I keep myself honest.

Say I write something about what two years of blogging taught me, and I mention in passing that the site runs in Docker. Tag: docker. Declared pillar: reflections. Build dead:

[content-pillars] post 'what-blogging-taught-me' declares pillar='reflections' but no tag in tags[] maps to that pillar. Either add a tag whose registered pillar is 'reflections' or change the declared pillar.

docker is registered as homelab. Nothing on the post maps to reflections. The validator won't let me silently have a post that doesn't belong to any tag series. If a post can't anchor any tag series, it shouldn't be published as a tag-anchored post. It should be published as something else, or it should get a tag that earns its place.

The validator also changes how I write. When I sit down to write a post and I want to tag it workflow, I have to ask: is this post part of a series I'm willing to commit to? If yes, fine. If no, the tag dies and I pick a real one.

I don't know if that counts as discipline or just an elaborate way to make my own builds fail. But the vibes never made me stop and ask.

The two ADRs that came out of this

The whole taxonomy lives in two architecture decision records, under docs/adr/ in this site's repo.

ADR 0001 — the four pillars, the tag registration rule, the coherent-series test. This is the constitution.

ADR 0002 — the SEO policy. How tag pages render, what metadata they expose, how they relate to pillar pages. This is the policy that turns the constitution into something Google can crawl.

The wayfinder pass gave me a rule I could encode in the validator.

I knew what the blog was about. I had been writing it for two years. I didn't have the taxonomy for what it was about until I counted the tags.

New tags go through me

There will be new tags. New tags require a PR to the registry (src/data/content-pillars.ts) with a one-line rationale that passes the coherent-series test. No agent mediates this. I'm the curator.

That's the right shape. Tags are mine. The agent can write the post, can audit the existing tags, can build the validator. The decision about whether a new tag earns its place is mine.

The death rate felt bad while I was doing it. Felt like I was throwing things away, or being too strict.

Then I read a tag page with three posts that actually belonged together, and I realized what the page would have looked like with seven tags on it, half of which lied. The page would have been unreadable. The reader would have clicked and bounced. The tag would have meant nothing.

Most of the work in this was deletion. 30 tags out of 41 went. The posts stayed. They're still about what they were about. The surviving tags earned their place.

Then I refreshed http://localhost:3000.

Still seeing old content. Weird. This never happens.

The Confusion

Honestly, this annoyed me more than it should have. I had just spent all this time fixing the post, and now I can't even see the changes?

Velite was supposed to watch files automatically, like some content management systems do. Velite doesn't watch by default - you have to configure it. I'd written about this exact issue in a previous post. The irony was not lost on me.

So I restarted the dev server, cleared cache, expecting everything to work. The new post showed up, but Velite still wasn't watching files. Changes only appeared when I restarted the server. This definitely is a regression on what I had previously configured.

What's Actually Going On?

Velite's docs say it supports watch mode, but it needs to be configured properly. The integration with Next.js happens through next.config.ts - that's where Velite gets initialized. If watch mode isn't set up there, Velite just runs once when the server starts and never again.

I opened next.config.ts at the root of my project. Here's what the file looked like:

import type { NextConfig } from 'next/config'

const nextConfig: NextConfig = {
  // some other config...
}

export default nextConfig

Oh. The Velite integration code was completely missing.

I found the Velite integration code in their Next.js docs. Here's what should have been in next.config.ts:

import type { NextConfig } from 'next/config'

const nextConfig: NextConfig = {
  // some other config...
}

// Velite integration
const isDev = process.env.NODE_ENV === 'development'
const isBuild = process.env.NODE_ENV === 'production'
if (!process.env.VELITE_STARTED && (isDev || isBuild)) {
  process.env.VELITE_STARTED = '1'
  import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))
}

export default nextConfig

But there was nothing there. Just Next.js config.

So that's why watch mode wasn't working. The code to start Velite at all was gone.

Why Was It Removed?

I checked git history to see when it disappeared. Found commit 1afe3e2 with message "Duplicate Velite build issue" that had removed all the Velite integration code. I figured I must have made a mistake.

So I restored the code from git. Velite was running again. Watch mode was working. Changes appeared instantly.

Then I remembered what the duplicate build issue actually was.

The Double Build Problem

When I deployed to Vercel, I was seeing Velite build twice in the logs:

[VELITE] building...
[VELITE] building... again

The logs showed Velite building twice. I still don't know the exact root cause, but what I observed was: Next.js was triggering Velite during its build process, and something else (Vercel's Velite integration?) was also triggering a build. Two builds were happening.

The original code was running Velite in both development (isDev) and production (isBuild). In production, when isBuild is true, Next.js runs during the build process. If Vercel also has its own Velite integration, both would be triggering Velite builds during deployment. That's inefficient. So commit 1afe3e2 removed the Velite integration entirely to stop the double builds.

The problem with that approach? It also broke watch mode in development because the commit removed ALL the integration code.

The Actual Fix

The real solution is to only run Velite watch mode in development. Vercel handles Velite builds separately in production (I verified this by checking my Vercel project settings - there's a "Velite" section that shows it runs builds during deployment), so Next.js shouldn't trigger them.

Here's what I ended up with:

const isDev = process.env.NODE_ENV === 'development'
if (!process.env.VELITE_STARTED && isDev) {
  process.env.VELITE_STARTED = '1'
  import('velite').then(m => m.build({ watch: true, clean: false }))
}

This is different from the original code:

• Removed isBuild - only run in development
• I ended up using watch: true in dev mode
• I ended up using clean: false in dev mode (I tried both settings. With clean: true, Velite would rebuild everything from scratch each time a file changed. With clean: false, it only rebuilt changed files, which was much faster)
• Vercel handles Velite builds separately in production (no watch mode needed)

The VELITE_STARTED environment variable prevents Velite from starting multiple times during Next.js hot reloads. Without it, every time Next.js reloaded the config (when files change), Velite would start again, which causes issues.

To verify this works, I changed the content in one of my blog posts without restarting the dev server. Within a second, the change appeared in the browser. I also checked my Vercel deploy logs and only saw one Velite build.

Happy days. Back in business.

If you're also setting up a blog with Velite, I wrote about the full Velite/Next.js setup process as well — this was part of that same initial build.

I had previously set up draft posts following my guide on adding draft posts to Velite. The frontmatter clearly said draft: true, but Velite didn't seem to care. My blog was showing posts that shouldn't exist yet - they appeared in the post list with full content visible, no indication they were drafts at all.

My Initial Setup

I'm using Velite 0.3.0 with Next.js 16.1.1. Here's what my velite.config.js looked like initially:

// velite.config.js (original)
export default defineConfig({
  collections: [
    {
      name: 'post',
      pattern: 'posts/**/*.md',
      schema: {
        // ... schema definition
      },
      filter: (post) => {
        const isProduction = process.env.VERCEL_ENV === 'production'
        return isProduction ? !post.draft : true
      }
    }
  ],
  // ... rest of config
})

The logic seemed sound: check if we're on Vercel production, and if so, filter out draft posts. In development, show everything including drafts.

This worked fine locally. I could see my drafts when writing, and published posts appeared on the blog. But when I deployed to Vercel, all my drafts went live.

First Suspicion: Maybe VERCEL_ENV Isn't Set at Build Time?

I had a suspicion that VERCEL_ENV wasn't being set correctly when Velite runs its build process. Vercel sets this environment variable, but maybe it's not available during the static site generation phase when Velite is processing posts.

I changed the config to use NODE_ENV instead, since that's definitely set during the build:

// velite.config.js (attempt 1)
filter: (post) => {
  const isProduction = process.env.NODE_ENV === 'production'
  return isProduction ? !post.draft : true
}

I was hoping this would work because NODE_ENV is set by Next.js when running npm run build, so it should be available when Velite processes the posts.

First Test: Still There

I ran the build:

NODE_ENV=production npm run build

Then checked .velite/posts.json to see what was generated. All 18 posts. Including 17 drafts.

I also checked what VERCEL_ENV was actually set to during the build:

// Quick debug check
filter: (post) => {
  console.log('VERCEL_ENV:', process.env.VERCEL_ENV)
  const isProduction = process.env.NODE_ENV === 'production'
  return isProduction ? !post.draft : true
}

Output: VERCEL_ENV: undefined - exactly what I suspected. The environment variable wasn't being set during Velite's build process.

Okay, so the filter function wasn't working as I expected.

Next I Tried: Check Timing of Environment Evaluation

I wondered if NODE_ENV was being evaluated when the module loads instead of when Velite actually processes each post. If the module loads before NODE_ENV is set to 'production', the filter would always see development mode.

But wait - that didn't make sense. I was explicitly running NODE_ENV=production npm run build, so the environment variable should be set before any Node modules load. The timing wasn't the issue.

Something else was going on.

Does the Filter Function Even Run?

Let me see if the filter function is even being called:

filter: (post) => {
  console.log('Filtering post:', post.title, 'draft:', post.draft)
  const isProduction = process.env.NODE_ENV === 'production'
  return isProduction ? !post.draft : true
}

Ran the build. I was watching the terminal where I ran npm run build, but no logs appeared there. The filter function wasn't being invoked at all, or at least not in a way that would show logs during the build process.

So I Tested the Filter Logic Itself

Maybe the filter function syntax was wrong? Let me test by making it always return false, which should exclude all posts:

filter: (post) => {
  console.log('Filtering post:', post.title)
  return false
}

Built again. Checked .velite/posts.json. All 18 posts still there.

At this point I was genuinely confused. The filter function exists in the Velite API, but it doesn't seem to affect the generated output at all. Either I'm using it wrong, or it's not doing what I think it does.

Filter in the complete() Callback

Velite has a complete() callback that runs after it generates all the data. Maybe filtering needs to happen there, since it's called after processing is complete?

I thought this might work because in my mental model, Velite processed the posts first, then wrote the JSON files, then called complete() to do final cleanup. If that was the case, modifying data.posts in complete() would affect what got written to the JSON file.

complete: (data) => {
  const isProduction = process.env.NODE_ENV === 'production'
  console.log('isProduction:', isProduction)
  console.log('Posts before filter:', data.posts.length)

  if (isProduction) {
    const draftCount = data.posts.filter(p => p.draft).length
    console.log('Filtering out', draftCount, 'draft posts')
    data.posts = data.posts.filter(post => !post.draft)
  }

  console.log('Posts after filter:', data.posts.length)
  // ... rest of function
}

Ran NODE_ENV=production npm run build.

Output:

isProduction: true
Posts before filter: 18
Filtering out 17 draft posts
Posts after filter: 1

Okay, so the filtering logic itself works! The logs show 1 post after filtering.

But when I opened .velite/posts.json to verify, I was surprised - all 18 posts were there. My mental model was wrong. The complete() callback must run AFTER the JSON files are written, or it doesn't affect the generated output files at all.

Either way, the filtering I was doing wasn't making it into the JSON file.

The Breakthrough

Then it clicked. Velite generates the JSON, but I don't have to use all of it. My app imports posts from .velite/posts.json in src/lib/posts.ts, where I sort them and prepare them for display. Why not filter there too?

This is runtime filtering - it happens right when the posts are accessed by my app, not during Velite's build process. That means NODE_ENV would definitely be set correctly because it's happening in the Next.js runtime.

I know build-time filtering is theoretically faster since filtering happens once during the build instead of on every request. But at this point, I was tired of debugging the build process and wanted something that actually worked. I can always optimize later if performance becomes an issue - right now, reliability matters more.

Here's what src/lib/posts.ts looked like before:

// src/lib/posts.ts (before)
import posts from '.velite/posts.json'
import { cache } from 'react'

export const getPosts = cache(() =>
  posts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())
)

And here's what I changed it to:

// src/lib/posts.ts (after)
import posts from '.velite/posts.json'
import { cache } from 'react'

const isProduction = process.env.NODE_ENV === 'production'
const filteredPosts = isProduction ? posts.filter(post => !post.draft) : posts

export const getPosts = cache(() =>
  filteredPosts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())
)

Now when getPosts() is called, it checks NODE_ENV and returns filtered posts if we're in production.

Before deploying, I wanted to verify locally:

NODE_ENV=production npm run build
NODE_ENV=production npm start

Opened localhost:3000 in the browser. Only the published post showed up. The drafts were gone.

Deployed to Vercel. Checked the production URL directly (not from cache - used an incognito window to be sure). Only the published post shows up. The drafts are gone.

Quick note about preview deployments: The NODE_ENV check I used means preview deployments on Vercel will also hide draft posts, since NODE_ENV is 'production' in preview builds. If you want drafts to show in preview deployments, you'd need to check VERCEL_ENV === 'production' instead. But for my use case, hiding drafts in all non-dev environments works fine.

Cleaning Up

I removed the filter logic from velite.config.js since it wasn't working anyway:

// velite.config.js (final)
export default defineConfig({
  collections: [
    {
      name: 'post',
      pattern: 'posts/**/*.md',
      schema: {
        // ... schema definition
      }
      // No filter function - filtering happens in src/lib/posts.ts
    }
  ],
  // ... rest of config
})

Committed with message: "Fix draft post filtering to work in production"

Ran npm run lint to make sure everything was clean. Deployed. Verified.

Now my drafts stay drafts, and published posts are the only ones visible in production.

I spent quite a while trying to make build-time filtering work in Velite before realizing runtime filtering in my app was actually the right approach.

These posts are often half-finished thoughts and content that I didn't want to be published yet. So to avoid this happening, but to still give me the ability to create a base post to work from, I thought I'd enable drafts that would be hidden until I was ready to publish.

"Just add draft: true to frontmatter," I thought. Every other static site generator does this, right?

Spoiler: Velite doesn't work that way.

Here's what I tried first:

---
title: "Work in Progress"
date: 2025-01-03
draft: true
---

Still writing this...

Except... it doesn't work that way.

The Question

"Does Velite automatically consider all frontmatter (those YAML settings at the top of my markdown files between the --- markers), or do we need to handle each value separately?"

I assumed Velite would auto-pick up any field I put in frontmatter. Add draft: true, filter posts by post.draft, done.

That's not how Velite works.

What I'm Starting With

Before I get into the solution, here's what my setup looked like:

My existing Velite schema (/velite.config.js):

import rehypeShiki from '@shikijs/rehype'
import { defineConfig, s } from 'velite'

export default defineConfig({
  collections: {
    posts: {
      name: 'Post',
      pattern: 'posts/**/*.md',
      schema: s
        .object({
          title: s.string().max(99),
          slug: s.slug('posts'),
          date: s.isodate(),
          lastModified: s.isodate().optional(),
          cover: s.image().optional(),
          video: s.file().optional(),
          metadata: s.metadata(),
          excerpt: s.excerpt(),
          content: s.markdown()
        })
        .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))
    }
  },
  markdown: {
    rehypePlugins: [
      [rehypeShiki, { theme: 'github-dark' }]
    ]
  }
})

Prerequisites: You should have:

• Velite 0.3.0+ installed
• A working posts collection
• Frontmatter with title, slug, date fields

If your setup looks different, the draft field addition should still work. You'll just need to adapt the schema structure.

How Velite Actually Works

I'm using Velite 0.3.0 with Next.js 16.1.1, and this is where I learned something important.

Velite is schema-first. Every field must be explicitly defined in your schema in /velite.config.js.

From Velite's official docs:

The schema property defines the structure and types of the data within a collection. You use Velite's schema system to specify fields, their types, and whether they are optional.

No schema field? No access to that data. Period.

This means:

1. Schema defines fields - What fields exist on your posts
2. Frontmatter provides values - The actual data for those fields
3. Velite validates - Ensures frontmatter matches schema at build time

If draft isn't in your schema, Velite ignores it in frontmatter.

What I Actually Did (And Got Wrong First)

Adding draft functionality requires two changes. I thought I could skip the first one. I was wrong.

1. Add the Field to Your Schema

I figured Velite would just... pick up the field. Add draft: true to frontmatter, access post.draft in my code, done.

Nope.

Velite ignored my draft field entirely. No error, no warning, nothing. The post compiled, the field was just... gone.

Here's what I added to my config:

import { defineCollection, defineConfig } from 'velite'
import { MDXPlugin } from 'velite-remark'
import rehypeSlug from 'rehype-slug'
import rehypeAutolinkHeadings from 'rehype-autolink-headings'

const posts = defineCollection({
  name: 'Post',
  pattern: 'posts/**/*.md',
  schema: s.object({
    title: s.string().max(99),
    slug: s.slug('posts'),
    date: s.isodate(),
    draft: s.boolean().optional().default(false), // ← Add this line
    // ... other existing fields like description, tags, etc.
  }),
  mdx: MDXPlugin({ rehypePlugins: [rehypeSlug, rehypeAutolinkHeadings] })
})

export default defineConfig({
  collections: { posts }
})

In my case, I had MDX plugins set up for syntax highlighting. If your setup is simpler, the schema addition looks like this:

const posts = defineCollection({
  name: 'Post',
  pattern: 'posts/**/*.md',
  schema: s.object({
    title: s.string().max(99),
    slug: s.slug('posts'),
    date: s.isodate(),
    draft: s.boolean().optional().default(false),
  })
})

export default defineConfig({ collections: { posts } })

Understanding the Schema Builder

The s object you see in the code examples is the schema builder. It's provided by defineCollection and gives you type-safe field definitions:

• s.string() - text fields
• s.boolean() - true/false values
• s.isodate() - date fields (validated as ISO format)
• s.slug() - URL-friendly slugs
• .optional() - field doesn't have to exist
• .default(false) - if missing, use this value
• .max(99) - string length limit

Why I Set It Up This Way

I chose .optional().default(false) and .boolean() for specific reasons:

• .optional() — not every post needs a draft flag, so we don't require it
• .default(false) — posts are published by default (safer than assuming draft)
• .boolean() — catches typos like draft: yes instead of true, failing at build time

Don't Forget Cache Clearing

I saved the config and restarted the dev server.

Still no draft field in my posts. I checked .velite/posts.json. Nothing.

Hmm. Maybe I typoed something in the schema? No, looks fine. Maybe the MDX plugins are interfering? I tried simplifying the config to just the schema. Still nothing.

At this point I remembered: Velite caches everything. Schema changes mean the cached data is invalid.

I ran npm run clean:dev (which removes both .next and .velite folders) and restarted the dev server.

This time, .velite/posts.json had the draft field for every post:

{
  "title": "Work in Progress",
  "slug": "work-in-progress",
  "date": "2025-01-03T00:00:00.000Z",
  "draft": true,
  // ... other fields
}

Posts without draft: true in frontmatter had "draft": false (from the .default(false)). I tested a typo (darft: true) which resulted in the field being ignored entirely, defaulting to false. Nice.

Lesson learned: Schema changes in Velite require clearing the cache. It's annoying, but it prevents stale cached data from causing weird bugs.

2. Add Environment-Aware Filtering

But having the field isn't enough. You also need to filter out drafts based on environment.

I needed:

• Local dev: Show all posts (including drafts)
• Vercel preview: Show all posts (for review)
• Production: Hide drafts

I considered using Vercel's VERCEL_ENV at first. That's the "proper" Vercel way. But I was already using NODE_ENV elsewhere in my config, so I stuck with that.

const isProduction = process.env.NODE_ENV === 'production'

This works because:

• Local dev means NODE_ENV=development, so show drafts
• Production build means NODE_ENV=production, so hide drafts

For the filtering, I added it in /src/lib/posts.ts rather than the Velite config. Here's what that looks like:

import { cache } from 'react'
import { posts } from '#site/content'

const isProduction = process.env.NODE_ENV === 'production'

// Filter posts at the application level
const filteredPosts = isProduction ? posts.filter(post => !post.draft) : posts

// All exported functions use filteredPosts instead of raw posts
export const getPosts = cache(() =>
  filteredPosts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())
)

export const getPostBySlug = cache((slug: string) =>
  filteredPosts.find((p) => p.slug === slug)
)

I filtered at the application level because it keeps the Velite config simple. I just need the schema field. The filtering logic lives with the rest of the post retrieval code, which felt cleaner to me.

How Draft Filtering Works Across Environments

Here's how it behaves:

• Local dev (NODE_ENV=development) means show drafts
• Vercel preview (NODE_ENV=production) means hide drafts
• Production (NODE_ENV=production) means hide drafts

The simple check process.env.NODE_ENV === 'production' handles all cases:

• Local dev gives isProduction = false, so show drafts
• Production build gives isProduction = true, so hide drafts

Why I'm Okay With This Now

Honestly, defining every field in the schema felt annoying at first. More boilerplate, more config.

But then I thought about what would happen without it:

Typo draft: true as darft: true? Build succeeds. Draft goes live. You don't notice until someone emails you.

Inconsistent values like draft: yes or draft: 1? No type checking. Your filter logic breaks silently.

Rename draft to published in frontmatter but forget to update code? No build error. Filtering stops working.

Schema-first means:

• Typos in field names → build fails immediately
• Wrong types → Velite catches it at build time
• Refactoring → TypeScript shows all usage

The 30 seconds to add a schema field saves hours of "why isn't this working?" debugging.

What About Vercel Deployments?

I initially thought about using VERCEL_ENV since I'm deploying to Vercel. That's what their docs recommend for detecting preview vs production deployments. But NODE_ENV works fine for my use case:

• I don't need separate preview deployments with different draft visibility
• NODE_ENV is already set by Vercel in production builds
• I was already using NODE_ENV elsewhere in my config

If you need draft posts visible in preview deployments but hidden in production, VERCEL_ENV is the way to go:

const isProduction = process.env.VERCEL_ENV === 'production'

// Then use the same filtering logic
const filteredPosts = isProduction ? posts.filter(post => !post.draft) : posts

But for me, NODE_ENV is simpler and works just as well.

My Actual Testing Experience

I created a test draft post to verify everything worked:

---
title: "Test Draft"
slug: test-draft
date: 2025-01-03
draft: true
---

This should only appear in dev/preview.

First, I ran npm run dev. The draft showed up in my post list. I clicked through to /blog/test-draft and saw the content. Good.

Then I ran npm run build followed by npm run start to test production behavior.

Expected: Post appears in list, I can read it. Actual: Post is gone from the list. /blog/test-draft returns 404.

Exactly what I wanted. But I wanted to double-check the build output, so I opened .velite/posts.json. Wait. The test-draft entry was still there.

That's weird. I thought it would be filtered out by Velite?

Oh right. I'm filtering at the application level in posts.ts, not in the Velite config. Velite builds all posts, including drafts, into .velite/posts.json. Then my application code filters them out when retrieving posts.

I verified this by checking the RSS feed. In the Velite config's complete callback, I filter out drafts before adding to the feed. So draft posts don't show up in the RSS. But .velite/posts.json still contains everything.

This is actually fine. The filtering happens where I retrieve posts, so draft posts never reach my components. The build output includes everything, but my app only serves what's appropriate for the environment.

What I Learned

Velite doesn't auto-pick up frontmatter fields. You must define them in your schema first.

This felt like a constraint at first. Now I see it as a safety net:

• Build-time validation catches mistakes
• TypeScript knows what fields exist
• Impossible states become... impossible

The schema isn't boilerplate. It's the contract between your content and your code.

That darft: true typo? Can't happen. Velite would ignore the field entirely, and TypeScript would show an error when you try to access post.darft.

Schema-first design saves future-you from current-you's mistakes.

I already had Velite working with Next.js (covered in my previous post), with posts in /content/posts/*.md and the dev server running on port 3000.

My code blocks were just... sad. Monospace text on a dark background. No syntax highlighting, no nothing. Made my blog posts look like they were written in Notepad.

For reference, my versions:

• Next.js ^16.1.1
• Velite ^0.3.0
• @shikijs/rehype ^3.20.0
• shiki ^3.15.0
• Node 20.18.0

Things might differ with other versions, especially with Next.js 16.

I wanted them to look like VS Code - proper colors for keywords, strings, functions, the whole deal. Shiki uses VS Code's actual syntax highlighting engine, so it seemed like the obvious choice.

Turns out "obvious" doesn't mean "straightforward." Here's what I ran into.

Setting Up Shiki

I needed two packages: Shiki itself, and the rehype plugin to hook it into Velite's markdown processing:

npm install @shikijs/rehype shiki

In my case, this grabbed shiki ^3.15.0 and @shikijs/rehype ^3.20.0.

Now it's time to hook this up in the Velite config. This is where I hit my first snag.

Problem #1: TypeScript Syntax in a JavaScript File

My first attempt:

import rehypeShiki from '@shikijs/rehype'

export default defineConfig({
  collections: { /* ... */ },
  markdown: {
    rehypePlugins: [
      [rehypeShiki as any, { theme: 'github-dark' }]
    ]
  }
})

Error:

Expected "]" but found "as"

The error was straightforward - my config file was velite.config.js (JavaScript), but I was using TypeScript syntax (as any). Just remove the type cast:

markdown: {
  rehypePlugins: [
    [rehypeShiki, { theme: 'github-dark' }]
  ]
}

Problem #2: Config Structure

I kept getting syntax errors because I couldn't get the braces right. The markdown key needs to be at the same level as collections, not inside it:

// This doesn't work - markdown inside collections
export default defineConfig({
  collections: {
    posts: { /* ... */ },
    markdown: { /* ... */ }
  }
})

// What actually works - markdown as sibling to collections
export default defineConfig({
  collections: {
    posts: { /* ... */ }
  },
  markdown: {
    rehypePlugins: [
      [rehypeShiki, { theme: 'github-dark' }]
    ]
  }
})

Count your braces carefully. I had to trace through mine multiple times.

One more thing: after changing velite.config.js, I had to clear the cache or nothing would work:

npm run clean:dev

Stop the dev server first, run the clean command, then restart. I forgot this the first time and spent 15 minutes wondering why nothing changed.

Problem #3: CSS Conflicts

Once Shiki was working, I had CSS fighting with it. My existing styles in /src/app/globals.css were overriding Shiki's colors.

I restarted the dev server, refreshed the page, and... nothing had changed. Code blocks were still just monospace text in my custom colors.

Wait, what? Shiki was supposed to be handling colors now.

I opened DevTools and saw inline styles like style="color: #ff79c6" on each code token. I realized Shiki generates these because it needs exact color control for syntax highlighting. My CSS's text-color property was more specific and overriding them.

When I disabled text-color in DevTools, Shiki colors instantly appeared. So I just needed to remove that property from my CSS and let Shiki's colors come through.

/* My initial approach - this was fighting with Shiki */
code {
  @apply bg-code-carbon text-neural-silver px-1.5 py-0.5 rounded font-mono text-sm;
}

pre {
  @apply bg-code-carbon/35 p-4 rounded-lg overflow-x-auto font-mono text-sm m-4;
}

pre code {
  @apply bg-transparent p-0 text-code-carbon;
}

The problem was that my colors were overriding Shiki's syntax highlighting.

Here's what's happening: Shiki generates inline styles on each code token (like style="color: #ff79c6" for keywords). My CSS was more specific and overriding these. What finally worked was letting Shiki handle colors for code blocks and only styling inline code myself:

/* Inline code */
article :not(pre) > code {
  @apply !bg-terminal-primary/15 !text-terminal-primary !px-1.5 !py-0.5 rounded-sm !font-mono !text-sm !border-none;
}

/* Code block container - let Shiki handle colors */
pre {
  @apply bg-terminal-dim/10 p-4 rounded-lg border border-terminal-dim/15 font-mono text-sm overflow-x-auto my-6;
}

/* Reset for code inside pre */
pre code {
  @apply !bg-transparent !p-0 !border-none !rounded-none !text-inherit;
}

Verifying It Works

When I checked a blog post after getting the CSS right, I finally saw:

• Inline code (like const foo = 'bar' in a paragraph) had my custom background color
• Code blocks had colorized syntax highlighting:
  • Keywords (like const, function, import) in purple/pink
  • Strings (like 'github-dark') in green
  • Comments in muted gray
  • Variables in light blue/white
• In the example const foo = 'bar', I saw const in one color and 'bar' in a different color

When my code blocks were still just monochrome text at first, I checked Shiki's theme preview to see what github-dark was supposed to look like. That's when I realized the Velite cache hadn't cleared properly. Ran npm run clean:dev one more time, restarted the dev server, and it worked.

Untagged Code Blocks Don't Get Highlighting

I noticed code blocks without a language specified don't get Shiki styling:

```
This has no syntax highlighting
```

Two options:

1. Always specify a language - use text or plaintext for non-code
2. Add fallback text color in CSS:

pre code {
  @apply bg-transparent p-0 text-inherit;
}

I went with always specifying languages since it's more explicit.

What Actually Worked

After all that debugging, here's what finally worked. Two files needed changes:

velite.config.js (mine's in the project root):

import { defineConfig, s } from 'velite'
import rehypeShiki from '@shikijs/rehype'

export default defineConfig({
  collections: {
    posts: {
      name: 'Post',
      pattern: 'posts/**/*.md',
      schema: s
        .object({
          title: s.string().max(99),
          slug: s.slug('posts'),
          date: s.isodate(),
          cover: s.image().optional(),
          video: s.file().optional(),
          metadata: s.metadata(),
          excerpt: s.excerpt(),
          content: s.markdown()
        })
        .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))
    }
  },
  markdown: {
    rehypePlugins: [
      [rehypeShiki, { theme: 'github-dark' }]
    ]
  }
})

globals.css (at /src/app/globals.css):

/* Inline code */
article :not(pre) > code {
  @apply !bg-terminal-primary/15 !text-terminal-primary !px-1.5 !py-0.5 rounded-sm !font-mono !text-sm !border-none;
}

pre {
  @apply bg-terminal-dim/10 p-4 rounded-lg border border-terminal-dim/15 font-mono text-sm overflow-x-auto my-6;
}

/* Reset prose code block styling - let Shiki handle it */
pre code {
  @apply !bg-transparent !p-0 !border-none !rounded-none !text-inherit;
}

Thinking back on it, the thing that would have saved me the most time was adding Shiki first. I spent time manually styling code blocks - choosing colors, tweaking spacing, getting everything just right. Then Shiki took over and I had to undo most of it.

Other stuff that tripped me up:

• File extensions matter - .js files can't use TypeScript syntax. Took me a few minutes of staring at Expected "]" but found "as" before I remembered the config was JavaScript, not TypeScript.

• Config structure is finicky - Velite has specific expectations about where keys go. Count your braces carefully.

• Specify languages in markdown - ```javascript gives proper highlighting, but ``` without a language just shows plain text.

Syntax highlighting is working now and my code blocks actually look like code blocks. Took way longer than I expected, but at least they look like code blocks now.

I spent hours yesterday fighting with Velite and Next.js 16. The docs said it should "just work." Instead I got TypeScript errors about exports not found, build failures from missing files in the schema, and a type error that turned out to be a Next.js 16 breaking change.

Here's what happened.

Where This Started

I got the idea to create a personal blog site where I can share what I'm working on. I did some research on various platforms, and consulted with Claude on potential options. In the end I decided a simple site based on static markdown files seemed like the most suitable option for my needs. I had no idea how to go about doing that so I googled it.

Every article pointed to Contentlayer for managing a simple blog. Except Contentlayer isn't maintained anymore. So I did what any developer does: searched Reddit for "what to use instead of Contentlayer." The consensus seemed to be that Velite was the successor.

Velite offers a lot of additional features like build-time processing and Typescript generation, which I knew nothing about at that point, but those turned out to be useful features I'd use later. I just wanted markdown files to show up as blog posts and Velite seemed to be a suitable option for that.

So I spun up a fresh Next.js project using npx create-next-app@latest and selected: TypeScript, ESLint, Tailwind CSS, App Router, Turbopack.

Then I ran npm install velite and created a basic config.

This is what my setup looked like:

• Node.js 20.10.0
• Next.js 16.1.1 with App Router
• React 19.2.0
• Velite 0.3.0
• TypeScript 5
• Running on Ubuntu via WSL2 using Turbopack

File structure:

.
├── velite.config.js
├── next.config.ts
├── tsconfig.json
├── .velite/          # Generated by Velite
├── posts/
│   └── my-first-post.md
└── app/
    ├── page.tsx
    └── blog/
        └── [slug]/
            └── page.tsx

The First Problem: Imports Don't Work

I installed Velite, created velite.config.js, ran npx velite, and tried to import posts:

import { posts } from 'velite';

But immediately encountered a problem: Error: The export posts was not found in module velite/dist/index.js

I stared at this for quite a few minutes. I assumed I'd import from the Velite package itself—that's how most npm packages work, right?

Then I actually checked the Velite docs again. Oh—you import from the .velite folder that Velite generates, not the package itself.

So I tried:

import { posts } from './.velite';

That worked. But then I found the docs mentioned path aliases as a cleaner option. So I created one in tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"],
      "#site/content": ["./.velite"]
    }
  }
}

After restarting the dev server, I tested the path alias approach:

import { posts } from '#site/content';

That worked.

The Second Problem: Velite Won't Run

So I tried running Velite:

[VELITE] Patterns must be a string (non empty) or an array of strings

I checked my config—everything looked fine. I'd copied it straight from the Velite quick start docs, so how could it be wrong?

Then I noticed the docs had this others collection:

collections: {
  posts: { /* ... */ },
  others: {
    // other collection schema options
  }
}

The others bit was just a placeholder showing you can have multiple collections. It wasn't required. I'd pasted it in verbatim without thinking about it.

Velite was complaining because the others collection didn't have a pattern field (like pattern: 'others/**/*.md'). Without a pattern, Velite doesn't know what files to include.

Deleted the others collection entirely. Ran npx velite again. This time: ✓ posts (1 documents).

The Third Problem: Missing Files Break Builds

Velite was running now. But looking at the Velite docs, I saw examples with cover and video fields. Figured I'd add those too—why not?

So I copied them into my schema:

cover: s.image(),
video: s.file(),

And put them in my test post:

---
title: My First Post
slug: my-first-post
date: 2025-11-16
---
cover: cover.jpg
video: video.mp4

But these files didn't exist. Velite errored out.

I should have started with a minimal post:

---
title: My First Post
slug: my-first-post
date: 2025-11-16
---
This is some markdown content.

Same pattern as before—the docs were showing me what's possible, not what I actually need. I made them optional in my schema:

cover: s.image().optional(),
video: s.file().optional(),

Updated the schema, ran npx velite, and it worked.

The Fourth Problem: Dynamic Routes 404ing

I got to the point where I could import posts in a listing page, but individual post routes kept 404ing even though the files were there.

I'd copied some example code from the docs for dynamic routes:

export default function PostPage({ params }: { params: { slug: string } }) {
  const post = posts.find((p) => p.slug === params.slug);
  // ...
}

TypeScript was complaining that params should be a Promise<{ slug: string }> instead of just { slug: string }. I ignored it at first because I assumed the example code was correct.

Turns out the example was from Next.js 14 or earlier. Next.js 15 changed params to be async for better performance, and Next.js 16 kept that change.

Here's what happens without await: Next.js expects an async function to handle the params promise. If you don't await it, the route handler won't execute properly—it just silently 404s.

So I needed to await the params:

export default async function PostPage({
  params
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params;
  const post = posts.find((p) => p.slug === slug);
  // ..
}

After this change, my dynamic routes loaded. No more 404s.

The Fifth Problem: Watch Mode Just... Didn't Work

This one took me the longest. I copied the integration code from the Velite docs into next.config.ts:

const isDev = process.argv.indexOf('dev') !== -1
const isBuild = process.argv.indexOf('build') !== -1
if (!process.env.VELITE_STARTED && (isDev || isBuild)) {
  process.env.VELITE_STARTED = '1'
  import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))
}

Started the dev server. No errors. But Velite never ran. I could edit markdown files all day—nothing happened.

Debugging the argv Issue

I'd been debugging for a while by this point and was stuck. I asked Claude for help, and it suggested adding some console.log statements to see what was actually in process.argv:

console.log('[DEBUG] isDev:', isDev, 'isBuild:', isBuild, 'argv:', process.argv)

Output showed both isDev and isBuild as false:

[DEBUG] isDev: false isBuild: false argv: [
  '/home/luke/.nvm/versions/node/v24.11.1/bin/node',
  '/home/luke/workspace/lukemanning-site/node_modules/next/dist/server/lib/start-server.js'
]

So 'dev' and 'build' weren't in argv at all.

The Velite integration code checks if 'dev' is in process.argv to decide whether to start watch mode. Since Turbopack's start-server.js doesn't include 'dev' in argv, that condition was never true—so Velite never started.

Next.js was using start-server.js internally instead of a simple command-line argument.

Claude suggested checking process.env.NODE_ENV as an alternative—since that's more reliable than parsing command-line arguments. Added that to my logging and saw it was set to 'development'. Worth a shot.

Changed it:

const isDev = process.env.NODE_ENV === 'development'
const isBuild = process.env.NODE_ENV === 'production'
if (!process.env.VELITE_STARTED && (isDev || isBuild)) {
  process.env.VELITE_STARTED = '1'
  import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))
}

Started the dev server again:

[VELITE] Building...
✓ posts (1 documents)
[VELITE] Watching for changes...

Edited a markdown file:

[VELITE] Rebuilding...
✓ posts (1 documents)

Finally worked.

I think what's happening is:

• Next.js 16 with Turbopack changed how the dev server starts internally
• It uses start-server.js as an intermediary instead of a simple next dev command
• The NODE_ENV environment variable is more reliable because it's set by Next.js regardless of how the server starts

Turbopack is enabled by default in Next.js 16 when you choose the recommended defaults in create-next-app, so I didn't even realize I was using it. The Velite docs acknowledge that Turbopack breaks their webpack plugin, and they provide a process.argv workaround—but that workaround doesn't actually work with Next.js 16's Turbopack setup.

My understanding could be wrong—I didn't dig into the Next.js source code—but the NODE_ENV approach has been rock-solid for two weeks now.

Where I Landed

After all that mess, here's where I ended up:

velite.config.js:

import { defineConfig, s } from 'velite'

export default defineConfig({
  collections: {
    posts: {
      name: 'Post',
      pattern: 'posts/**/*.md',
      schema: s
        .object({
          title: s.string().max(99),
          slug: s.slug('posts'),
          date: s.isodate(),
          cover: s.image().optional(),
          video: s.file().optional(),
          metadata: s.metadata(),
          excerpt: s.excerpt(),
          content: s.markdown()
        })
        .transform(data => ({ ...data, permalink: `/blog/${data.slug}` }))
    }
  }
})

next.config.ts:

import type { NextConfig } from "next";

const isDev = process.env.NODE_ENV === 'development'
const isBuild = process.env.NODE_ENV === 'production'
if (!process.env.VELITE_STARTED && (isDev || isBuild)) {
  process.env.VELITE_STARTED = '1'
  import('velite').then(m => m.build({ watch: isDev, clean: !isDev }))
}

const nextConfig: NextConfig = {};

export default nextConfig;

Just the paths section from tsconfig.json:

"paths": {
  "@/*": ["./*"],
  "#site/content": ["./.velite"]
}

Next Steps

Once you have Velite running with Next.js, you might also want to set up draft post filtering so unfinished posts don't accidentally go live, and add syntax highlighting with Shiki to make your code blocks actually readable.