nuxt-content

What this skill does

# 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.1.12, 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

```bash
# 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

```ts
// 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

```ts
// 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:
```md
<!-- 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

```vue
<!-- 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:

```ts
// 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(),
        tags: z.array(z.string()).default([])
      })
    }),

    authors: defineCollection({
      type: 'data',
      source: 'authors/*.yml',
      schema: z.object({
        name: z.string(),
        bio: z.string()
      })
    })
  }
})
```

---

### Collection Types

#### Page Type (`type: 'page'`)

**Use for**: Content that maps to URLs

**Features**:
- Auto-generates paths from file structure
- Built-in fields: `path`, `title`, `description`, `body`, `navigation`
- Perfect for: blogs, docs, marketing pages

**Path Mapping**:
```
content/index.md        → /
content/about.md        → /about
content/blog/hello.md   → /blog/hello
```

#### Data Type (`type: 'data'`)

**Use for**: Structured data without URLs

**Features**:
- Complete schema control
- No automatic path generation
- Perfect for: authors, products, configs

---

### Schema Validation

#### With Zod v4 (Recommended)

```bash
bun add -D zod@^4.1.12
# or: npm install -D zod@^4.1.12
```

```ts
import { z } from 'zod'

schema: z.object({
  title: z.string(),
  date: z.date(),
  published: z.boolean().default(false),
  tags: z.array(z.string()).optional(),
  category: z.enum(['news', 'tutorial', 'update'])
})
```

#### With Valibot (Alternative)

```bash
bun add -D valibot@^0.42.0
# or: npm install -D valibot@^0.42.0
```

```ts
import * as v from 'valibot'

schema: v.object({
  title: v.string(),
  date: v.date(),
  published: v.boolean(false),
  tags: v.optional(v.array(v.string()))
})
```

---

## Querying Content

### Basic Queries

```ts
// Get all posts
const posts = await queryCollection('blog').all()

// Get single post by path
const post = await queryCollection('blog').path('/blog/hello').first()

// Get post by ID
const post = await queryCollection('blog').where('_id', '=', 'hello').first()
```

---

### Field Selection

```ts
// Select specific fields (performance optimization)
const posts = await queryCollection('blog')
  .only(['title', 'description', 'date', 'path'])
  .all()

// Exclude fields
const posts = await queryCollection('blog')
  .without(['body'])
  .all()
```

---

### Where Conditions

```ts
// Single condition
const posts = await queryCollection('blog')
  .where('published', '=', true)
  .all()

// Multiple conditions
const posts = await queryCollection('blog')
  .where('published', '=', true)
  .where('category', '=', 'tutorial')
  .all()

// Operators: =, !=, <, <=, >, >=, in, not-in, like
const recent = await queryCollection('blog')
  .where('date', '>', new Date('2024-01-01'))
  .all()

const tagged = await queryCollection('blog')
  .where('tags', 'in', ['nuxt', 'vue'])
  .all()
```

---

### Ordering and Pagination

```ts
// Sort by field
const posts = await queryCollection('blog')
  .sort('date', 'DESC')
  .all()

// Pagination
const posts = await queryCollection('blog')
  .sort('date', 'DESC')
  .limit(10)
  .offset(0)
  .all()
```

---

### Counting

```ts
// Count results
const total = await queryCollection('blog')
  .where('published', '=', true)
  .count()
```

---

#