/nuxt-content

name: nuxt-content
description: "Nuxt Content v3 Git-based CMS for Markdown/MDC content sites. Use for blogs, docs, content-driven apps with type-safe queries, schema validation (Zod/Valibot), full-text search, navigation utilities. Supports Nuxt Studio production editing, Cloudflare D1/Pages deployment, Vercel deployment, SQL storage, MDC components, content collections."

metadata:
  keywords:
    - nuxt content
    - "@nuxt/content"
    - content collections
    - git-based cms
    - markdown cms
    - mdc syntax
    - nuxt studio
    - content editing
    - queryCollection
    - cloudflare d1 deployment
    - vercel deployment
    - markdown components
    - prose components
    - content navigation
    - full-text search
    - type-safe queries
    - sql storage
    - content schema validation
    - zod validation
    - valibot
    - remote repositories
    - content queries
    - queryCollectionNavigation
    - queryCollectionSearchSections
    - ContentRenderer component

license: MIT

Nuxt Content v3

**Status**: Production Ready **Last Updated**: 2025-01-10 **Dependencies**: None **Latest Versions**: @nuxt/content@^3.0.0, nuxt-studio@^0.1.0-alpha, zod@^4.3.6, valibot@^0.42.0, better-sqlite3@^11.0.0

---

Overview

Nuxt Content v3 is a powerful Git-based CMS for Nuxt projects that manages content through Markdown, YAML, JSON, and CSV files. It transforms content files into structured data with type-safe queries, automatic validation, and SQL-based storage for optimal performance.

What's New in v3

**Major Improvements**:

• **Content Collections**: Structured data organization with type-safe queries, automatic validation, and advanced query builder
• **SQL-Based Storage**: Production uses SQL (vs. large bundle sizes in v2) for optimized queries and universal compatibility (server/serverless/edge/static)
• **Full TypeScript Integration**: Automatic types for all collections and APIs
• **Enhanced Performance**: Ultra-fast data retrieval with adapter-based SQL system
• **Nuxt Studio Integration**: Self-hosted content editing in production with GitHub sync

When to Use This Skill

Use this skill when:

• Building blogs, documentation sites, or content-heavy applications
• Managing content with Markdown, YAML, JSON, or CSV files
• Implementing Git-based content workflows
• Creating type-safe content queries
• Deploying to Cloudflare (Pages/Workers) or Vercel
• Setting up production content editing with Nuxt Studio
• Building searchable content with full-text search
• Creating navigation systems from content structure

---

Quick Start (10 Minutes)

1. Install Nuxt Content

# Bun (recommended)
bun add @nuxt/content better-sqlite3

# npm
npm install @nuxt/content better-sqlite3

# pnpm
pnpm add @nuxt/content better-sqlite3

**Why this matters:**

• `@nuxt/content` is the core CMS module
• `better-sqlite3` provides SQL storage for optimal performance
• Zero configuration required for basic usage

2. Register Module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content']
})

**CRITICAL:**

• Module must be added to `modules` array (not `buildModules`)
• No additional configuration needed for basic setup

3. Create First Collection

// content.config.ts
import { defineContentConfig, defineCollection } from '@nuxt/content'
import { z } from 'zod'

export default defineContentConfig({
  collections: {
    content: defineCollection({
      type: 'page',
      source: '**/*.md',
      schema: z.object({
        tags: z.array(z.string()).optional(),
        date: z.date().optional()
      })
    })
  }
})

Create content file:

<!-- content/index.md -->
---
title: Hello World
description: My first Nuxt Content page
tags: ['nuxt', 'content']
---

# Welcome to Nuxt Content v3

This is my first content-driven site!

4. Query and Render Content

<!-- pages/[...slug].vue -->
<script setup>
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () =>
  queryCollection('content').path(route.path).first()
)
</script>

<template>
  <ContentRenderer v-if="page" :value="page" />
</template>

**See Full Template**: `templates/blog-collection-setup.ts`

---

Critical Rules

Always Do

1. **Define Collections** in `content.config.ts` before querying 2. **Use ISO 8601 Date Format**: `2024-01-15` or `2024-01-15T10:30:00Z` 3. **Restart Dev Server** after changing `content.config.ts` 4. **Use `.only()`** to select specific fields (performance) 5. **Place MDC Components** in `components/content/` directory 6. **Use Zero-Padded Prefixes** for numeric sorting: `01-`, `02-` 7. **Install Database Connector**: `better-sqlite3` required 8. **Specify Language** in code blocks for syntax highlighting 9. **Use `<!--more-->`** in content to separate excerpts 10. **D1 Binding Must Be "DB"** (case-sensitive) on Cloudflare

Never Do

1. **Don't Query Before Defining Collection** in `content.config.ts` 2. **Don't Use Non-ISO Date Formats** (e.g., "January 15, 2024") 3. **Don't Forget to Restart** dev server after config changes 4. **Don't Query All Fields** when you only need some (use `.only()`) 5. **Don't Place Components** outside `components/content/` 6. **Don't Use Single-Digit Prefixes** (use `01-` not `1-`) 7. **Don't Skip Database Connector** installation 8. **Don't Forget Language** in code fences 9. **Don't Expect Excerpts** without `<!--more-->` divider 10. **Don't Use Different Binding Names** for D1 (must be "DB")

---

Content Collections

Defining Collections

Collections organize related content with shared configuration:

// content.config.ts
import { defineCollection, defineContentConfig } from '@nuxt/content'
import { z } from 'zod'

export default defineContentConfig({
  collections: {
    blog: defineCollection({
      type: 'page',
      source: 'blog/**/*.md',
      schema: z.object({
        title: z.string(),
        date: z.date(),
        ta