Nuxt Content

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

# 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(),
        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)

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

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)

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

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

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

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

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

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

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

---

Server-Side Queries

// server/api/posts.get.ts
export default defineEventHandler(async (event) => {
  const posts = await queryCollection('blog')
    .where('published', '=', true)
    .sort('date', 'DESC')
    .all()

  return { posts }
})

---

Navigation

Auto-generate navigation tree from content structure:

const navigation = await queryCollectionNavigation('blog').all()

Returns hierarchical structure:

[
  {
    title: 'Getting Started',
    path: '/docs/getting-started',
    children: [{ title: 'Installation', path: '/docs/getting-started/installation' }]
  }
]

Advanced patterns (filters, ordering, custom structures): See references/collection-examples.md

---

MDC Syntax (Markdown Components)

Basic Component Syntax

<!-- Default slot -->
::my-alert
This is an alert message
::

<!-- Named slots -->
::my-card
#title
Card Title
#default
Card content here
::

Component:

<!-- components/content/MyAlert.vue -->
<template>
  <div class="alert">
    <slot />
  </div>
</template>

---

Props

::my-button{href="/docs" type="primary"}
Click me
::

Component:

<!-- components/content/MyButton.vue -->
<script setup>
defineProps<{
  href: string
  type: 'primary' | 'secondary'
}>()
</script>

---

Full-Text Search

// Search across all content
const results = await queryCollectionSearchSections('blog', 'nuxt content')
  .where('published', '=', true)
  .all()

Returns:

[
  {
    id: 'hello',
    path: '/blog/hello',
    title: 'Hello World',
    content: '...matching text...'
  }
]

---

Deployment

Cloudflare Pages + D1

bun add -D @nuxthub/core
bunx wrangler d1 create nuxt-content
bun run build && bunx wrangler pages deploy dist

wrangler.toml:

[[d1_databases]]
binding = "DB"  # Must be exactly "DB" (case-sensitive)
database_name = "nuxt-content"
database_id = "your-database-id"

CRITICAL: D1 binding MUST be named DB (case-sensitive).

See: references/deployment-checklists.md for complete Cloudflare deployment guide with troubleshooting.

---

Vercel

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  routeRules: {
    '/blog/**': { prerender: true }
  }
})

vercel deploy

See: references/deployment-checklists.md for complete Vercel configuration and prerender strategy.

---

Nuxt Studio Integration

Enable Studio

bun add -D nuxt-studio@alpha
# or: npm install -D nuxt-studio@alpha

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content', 'nuxt-studio'],
  
  studio: {
    enabled: true,
    gitInfo: {
      name: 'your-name',
      email: 'your-email@example.com'
    }
  }
})

OAuth Setup

1. Create GitHub OAuth App 2. Set Authorization callback URL: https://yourdomain.com/api/__studio/oauth/callback 3. Add client ID and secret to environment variables

CRITICAL: Callback URL must match production domain exactly (including https://).

---

Top 5 Critical Issues

Issue #1: Collection Not Found

Error: Collection 'xyz' not found

Solution: Define collection in content.config.ts and restart dev server

rm -rf .nuxt && bun dev

---

Issue #2: Date Validation Failure

Error: Validation error: Expected date, received string

Solution: Use ISO 8601 format:

---
date: 2024-01-15  # ✅ Correct
# NOT: "January 15, 2024"  # ❌ Wrong
---

---

Issue #3: D1 Binding Not Found (Cloudflare)

Error: DB is not defined

Solution: D1 binding name must be exactly DB (case-sensitive) in Cloudflare dashboard.

---

Issue #4: MDC Components Not Rendering

Error: Components show as raw text

Solution: Place components in components/content/ with exact name matching:

<!-- components/content/MyAlert.vue -->

::my-alert
Content
::

---

Issue #5: Navigation Not Updating

Error: New content doesn't appear in navigation

Solution: Clear .nuxt cache:

rm -rf .nuxt && bun dev

---

See All 18 Issues: references/error-catalog.md

---

When to Load References

Load `references/error-catalog.md` when:

• User encounters error beyond Top 5 shown above
• Debugging collection validation, schema errors, or deployment issues
• Need complete error catalog with all 18 documented solutions and sources

Load `references/collection-examples.md` when:

• Setting up advanced collection types (data vs page)
• Implementing complex schema validation patterns
• Need examples for Zod v4 or Valibot schemas
• Working with multiple collection configurations

Load `references/query-operators.md` when:

• Building complex queries beyond basic examples
• Need full reference of all operators (=, !=, <, >, <=, >=, in, not-in, like)
• Implementing pagination, sorting, or field selection
• Troubleshooting query syntax errors

Load `references/deployment-checklists.md` when:

• Deploying to specific platform (Cloudflare Pages, Cloudflare Workers D1, Vercel)
• Setting up production environment configurations
• Troubleshooting deployment-specific errors (D1 binding, prerender routes)
• Need platform-specific wrangler.toml or vercel.json examples

Load `references/mdc-syntax-reference.md` when:

• Implementing custom MDC (Markdown Components)
• Debugging component rendering issues
• Need complete syntax reference for props, slots, nesting
• Creating advanced content components

Load `references/studio-setup-guide.md` when:

• Setting up Nuxt Studio for production content editing
• Configuring GitHub OAuth authentication
• Enabling self-hosted content editing with GitHub sync
• Troubleshooting Studio authentication or Git sync issues

Templates (templates/):

• blog-collection-setup.ts - Complete blog setup with collections, queries, navigation, search, and deployment (334 lines)

---

Performance Tips

1. Use `.only()` to select specific fields 2. Enable Caching for production 3. Use Pagination for large collections 4. Prerender Static Routes on Vercel 5. Use SQL Storage (better-sqlite3) for optimal performance

---

Best Practices

1. Always define collections before querying 2. Use TypeScript for type-safe queries 3. Validate schemas with Zod or Valibot 4. Place MDC components in components/content/ 5. Use ISO 8601 date format 6. Add <!--more--> for excerpts 7. Specify language in code blocks 8. Clear .nuxt after config changes 9. For Cloudflare: D1 binding must be "DB" 10. Use pagination for large datasets

---

Integration with Other Skills

This skill composes well with:

• nuxt-v4 → Core Nuxt framework
• nuxt-ui-v4 → UI component library
• cloudflare-worker-base → Cloudflare deployment
• tailwind-v4-shadcn → Styling
• drizzle-orm-d1 → Additional database queries
• cloudflare-d1 → Database integration

---

Secure Installation

When installing CMS packages, follow supply chain security best practices:

• Block post-install scripts — npm config set ignore-scripts true (or Bun: disabled by default)
• Cooldown period — Wait 7 days for new package versions to be vetted by the community
• Audit before installing — Run socket package score npm <pkg> or use socket npm install <pkg> to check packages

Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

Additional Resources

Official Documentation:

• Nuxt Content Docs: https://content.nuxt.com
• GitHub: https://github.com/nuxt/content
• Nuxt Studio: https://nuxt.studio

Examples:

• Official Examples: https://github.com/nuxt/content/tree/main/examples
• Starter Templates: https://github.com/nuxt-themes

---

Production Tested: Documentation sites, blogs, content platforms Last Updated: 2025-01-27 Token Savings: ~60% (reduces content + error documentation)

Nuxt Content Collection Examples

Quick reference for common collection patterns.

Blog Collection

// 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(),
        description: z.string(),
        date: z.date(),
        author: z.string(),
        tags: z.array(z.string()).default([]),
        image: z.string(),
        published: z.boolean().default(false),
        category: z.enum(['news', 'tutorial', 'update'])
      })
    })
  }
})

File Structure:

content/
  blog/
    2024-01-15-first-post.md
    2024-01-20-second-post.md

Query Examples:

// List all published posts
const posts = await queryCollection('blog')
  .where('published', '=', true)
  .order('date', 'DESC')
  .all()

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

// Filter by category and tags
const tutorials = await queryCollection('blog')
  .where('category', '=', 'tutorial')
  .where('tags', 'IN', ['nuxt', 'vue'])
  .all()

---

Documentation Collection

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: 'docs/**/*.md',
      schema: z.object({
        title: z.string(),
        description: z.string(),
        category: z.string(),
        order: z.number().optional(),
        badge: z.string().optional(),
        icon: z.string().optional()
      })
    })
  }
})

File Structure (with numeric prefixes):

content/
  docs/
    01-getting-started/
      01-installation.md
      02-configuration.md
    02-guides/
      01-basics.md
      02-advanced.md

Query with Navigation:

// Get navigation tree
const navigation = await queryCollectionNavigation('docs')

// Get specific page
const page = await queryCollection('docs')
  .path(route.path)
  .first()

// Get breadcrumbs
const breadcrumb = findPageBreadcrumb(navigation, route.path)

---

Authors (Data Collection)

export default defineContentConfig({
  collections: {
    authors: defineCollection({
      type: 'data',  // Not URL-mapped
      source: 'authors/*.yml',
      schema: z.object({
        name: z.string(),
        bio: z.string(),
        avatar: z.string(),
        email: z.string().email(),
        social: z.object({
          github: z.string(),
          twitter: z.string().optional(),
          website: z.string().url().optional()
        })
      })
    })
  }
})

File: content/authors/john-doe.yml

name: John Doe
bio: Full-stack developer
avatar: /images/john.jpg
email: john@example.com
social:
  github: johndoe
  twitter: johndoe
  website: https://johndoe.com

Query:

// Get author by ID
const author = await queryCollection('authors')
  .where('id', '=', 'john-doe')
  .first()

// Get all authors
const authors = await queryCollection('authors').all()

---

Multi-Language Collection

export default defineContentConfig({
  collections: {
    en: defineCollection({
      type: 'page',
      source: {
        include: 'en/**/*.md',
        prefix: '/en'
      }
    }),

    fr: defineCollection({
      type: 'page',
      source: {
        include: 'fr/**/*.md',
        prefix: '/fr'
      }
    })
  }
})

File Structure:

content/
  en/
    index.md
    about.md
    blog/
      post-1.md
  fr/
    index.md
    about.md
    blog/
      post-1.md

URLs:

• /en → content/en/index.md
• /en/about → content/en/about.md
• /fr → content/fr/index.md
• /fr/about → content/fr/about.md

---

Products Collection (E-Commerce)

export default defineContentConfig({
  collections: {
    products: defineCollection({
      type: 'page',
      source: 'products/**/*.md',
      schema: z.object({
        name: z.string(),
        description: z.string(),
        price: z.number(),
        sku: z.string(),
        category: z.string(),
        images: z.array(z.string()),
        inStock: z.boolean().default(true),
        tags: z.array(z.string()).default([]),
        specifications: z.object({
          weight: z.string().optional(),
          dimensions: z.string().optional(),
          color: z.string().optional()
        }).optional()
      })
    }),

    categories: defineCollection({
      type: 'data',
      source: 'categories/*.json',
      schema: z.object({
        name: z.string(),
        slug: z.string(),
        description: z.string(),
        image: z.string()
      })
    })
  }
})

Query Products:

// Get products by category
const products = await queryCollection('products')
  .where('category', '=', 'electronics')
  .where('inStock', '=', true)
  .where('price', '<', 1000)
  .order('price', 'ASC')
  .all()

// Search products
const results = await queryCollection('products')
  .where('name', 'LIKE', '%phone%')
  .all()

---

Remote Repository Collection

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: {
        include: 'docs/**/*.md',
        repository: 'https://github.com/username/docs-repo',
        authToken: process.env.GITHUB_TOKEN  // For private repos
      }
    })
  }
})

Environment Variable:

# .env
GITHUB_TOKEN=ghp_your_token_here

---

With Nuxt Studio Editor Metadata

import { property } from '@nuxt/content'

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

        // Media picker in Studio
        image: property(z.string()).editor({
          input: 'media'
        }),

        // Dropdown select
        category: property(z.string()).editor({
          input: 'select',
          options: ['news', 'tutorial', 'update']
        }),

        // Toggle switch
        featured: property(z.boolean()).editor({
          input: 'toggle'
        })
      })
    })
  }
})

---

Best Practices

✅ Use meaningful collection names: blog, docs, products, not collection1 ✅ Define schemas for all fields: Enables validation and TypeScript types ✅ Use `type: 'page'` for URLs: Blog posts, docs, products ✅ Use `type: 'data'` for metadata: Authors, categories, settings ✅ Add defaults for optional fields: z.boolean().default(false) ✅ Use enums for fixed values: z.enum(['news', 'tutorial']) ✅ Organize with subdirectories: blog/, docs/, authors/

Deployment Checklists

Cloudflare Pages Checklist

Prerequisites

• [ ] Cloudflare account
• [ ] Wrangler CLI installed (optional)
• [ ] D1 database created

Configuration

• [ ] Build preset: cloudflare_pages in nuxt.config.ts
• [ ] Build command: npm run build
• [ ] Build output: .output/public

D1 Database

• [ ] D1 database created (nuxt-content-db)
• [ ] D1 binding configured
• [ ] Binding name is exactly DB (case-sensitive)

Environment Variables

• [ ] STUDIO_GITHUB_CLIENT_ID (if using Studio)
• [ ] STUDIO_GITHUB_CLIENT_SECRET (if using Studio)
• [ ] Custom env vars as needed

Deployment

• [ ] GitHub repository connected
• [ ] Build successful
• [ ] D1 binding active
• [ ] Custom domain configured (optional)
• [ ] SSL/TLS verified

Verification

• [ ] Site loads correctly
• [ ] Content queries work
• [ ] Studio accessible (if configured)
• [ ] No console errors

---

Cloudflare Workers Checklist

Configuration

• [ ] Build preset: cloudflare in nuxt.config.ts
• [ ] wrangler.toml configured
• [ ] D1 binding in wrangler.toml

wrangler.toml Example

name = "nuxt-content-worker"
main = ".output/server/index.mjs"
compatibility_date = "2024-01-01"

[[d1_databases]]
binding = "DB"
database_name = "nuxt-content-db"
database_id = "your-database-id"

Deployment

• [ ] Build: nuxi build --preset=cloudflare
• [ ] Deploy: wrangler deploy

---

Vercel Checklist

Prerequisites

• [ ] Vercel account
• [ ] Vercel CLI installed (optional)

Configuration

• [ ] Framework: Nuxt (auto-detected)
• [ ] Build command: npm run build
• [ ] Output directory: .output

Environment Variables

• [ ] STUDIO_GITHUB_CLIENT_ID (if using Studio)
• [ ] STUDIO_GITHUB_CLIENT_SECRET (if using Studio)
• [ ] POSTGRES_URL (if using Vercel Postgres)
• [ ] Custom env vars as needed

Database Options

Choose one:

• [ ] SQLite at /tmp (default, zero config)
• [ ] Vercel Postgres (create in dashboard)
• [ ] Vercel KV (key-value store)
• [ ] Vercel Blob (file storage)

Deployment

• [ ] GitHub repository connected
• [ ] Build successful
• [ ] Environment variables added
• [ ] Custom domain configured (optional)
• [ ] SSL certificate active

Route Rules (Optional)

routeRules: {
  '/': { prerender: true },
  '/blog/**': { swr: 3600 },      // Cache 1 hour
  '/docs/**': { isr: 3600 },      // ISR
  '/_studio/**': { ssr: true }
}

Verification

• [ ] Site loads correctly
• [ ] Content queries work
• [ ] Studio accessible (if configured)
• [ ] Preview deployments work

---

Netlify Checklist

Configuration

• [ ] Build command: npm run build
• [ ] Publish directory: .output/public
• [ ] Functions directory: .output/server

Environment Variables

• [ ] Add Studio credentials (if using)
• [ ] Add custom env vars

Deployment

• [ ] GitHub connected
• [ ] Build settings configured
• [ ] Deploy successful

---

General Checklist (All Platforms)

Pre-Deployment

• [ ] All dependencies installed
• [ ] content.config.ts configured
• [ ] Collections defined
• [ ] Content files created
• [ ] Local build successful: npm run build
• [ ] Dev server works: npm run dev

Post-Deployment

• [ ] Site accessible
• [ ] Content renders correctly
• [ ] Navigation works
• [ ] Search works (if implemented)
• [ ] Studio works (if configured)
• [ ] No 404 errors
• [ ] No console errors
• [ ] Performance acceptable

SEO & Meta

• [ ] Meta tags configured
• [ ] OG images working
• [ ] Sitemap generated
• [ ] Robots.txt configured

Monitoring

• [ ] Error tracking setup
• [ ] Analytics configured
• [ ] Performance monitoring

---

Hybrid Rendering Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: ['/']
    }
  },

  routeRules: {
    // Static at build time
    '/': { prerender: true },
    '/about': { prerender: true },

    // ISR (Incremental Static Regeneration)
    '/blog/**': { isr: 3600 },  // Regenerate every hour

    // SWR (Stale While Revalidate)
    '/docs/**': { swr: 3600 },  // Cache 1 hour

    // Always SSR
    '/_studio/**': { ssr: true },
    '/api/**': { cors: true }
  }
})

---

Troubleshooting

Build Fails

1. Check build logs 2. Verify all dependencies installed 3. Test locally: npm run build 4. Check Node.js version compatibility

Content Not Loading

1. Verify database configured (D1 or SQLite) 2. Check bindings (Cloudflare) 3. Test queries in development 4. Check console for errors

Studio Not Working

1. Verify SSR enabled 2. Check OAuth credentials 3. Verify callback URLs 4. Check environment variables 5. Test in development first

Performance Issues

1. Enable route rules (caching) 2. Prerender static pages 3. Implement pagination 4. Optimize images 5. Use CDN

Nuxt Content v3 - Complete Error Catalog

This document contains all 18 documented issues and their solutions for Nuxt Content v3.

Last Updated: 2025-01-10 Nuxt Content Version: 3.0.0 Source: Production deployments, GitHub issues, Nuxt Content documentation

---

Issue #1: Collection Not Found Error

Error: Collection 'xyz' not found

Source: https://github.com/nuxt/content/issues

Why It Happens: Collection not defined in content.config.ts or dev server not restarted

Prevention: Always define collections in content.config.ts and restart dev server after changes

Solution:

// content.config.ts
export default defineContentConfig({
  collections: {
    xyz: defineCollection({
      type: 'page',
      source: 'xyz/**/*.md'
    })
  }
})

Then restart: rm -rf .nuxt && bun dev

---

Issue #2: Schema Validation Failure with Dates

Error: Validation error: Expected date, received string

Source: https://github.com/nuxt/content/discussions

Why It Happens: Incorrect date format in frontmatter

Prevention: Use ISO 8601 format: 2024-01-15 or 2024-01-15T10:30:00Z

Solution:

---
title: My Post
date: 2024-01-15  # ✅ ISO 8601 format
# NOT: "January 15, 2024"  # ❌ Invalid
---

---

Issue #3: Database Locked Error

Error: SQLITE_BUSY: database is locked

Source: https://github.com/nuxt/content/issues

Why It Happens: Multiple processes accessing database simultaneously

Prevention: Delete .nuxt directory and restart dev server

Solution:

rm -rf .nuxt
bun dev

Note: This can happen when running multiple dev servers or after force-killing a process.

---

Issue #4: D1 Binding Not Found on Cloudflare

Error: DB is not defined

Source: Cloudflare D1 documentation

Why It Happens: D1 binding name is not exactly DB

Prevention: Use binding name DB (case-sensitive) in Cloudflare dashboard

Solution: 1. Go to Cloudflare Dashboard → Workers & Pages → Your project → Settings → Variables 2. D1 Database Bindings → Variable name must be exactly DB 3. Redeploy after changing binding name

---

Issue #5: MDC Components Not Rendering

Error: Components show as raw text instead of rendering

Source: MDC documentation

Why It Happens: Component not in components/content/ or incorrect syntax

Prevention: Place components in components/content/ with exact name matching

Solution:

<!-- components/content/MyAlert.vue -->
<template>
  <div class="alert">
    <slot />
  </div>
</template>

<!-- content/page.md -->
::my-alert
This is an alert message
::

Important: Component name in markdown uses kebab-case, Vue file uses PascalCase.

---

Issue #6: Navigation Not Updating

Error: New content doesn't appear in navigation

Source: https://github.com/nuxt/content/issues

Why It Happens: .nuxt cache not cleared

Prevention: Delete .nuxt directory when adding new content files

Solution:

rm -rf .nuxt
bun dev

---

Issue #7: Path Not Resolved Correctly

Error: Content returns null for valid path

Source: https://github.com/nuxt/content/discussions

Why It Happens: Path doesn't match file structure or prefix misconfigured

Prevention: Use .all() to debug paths

Solution:

// Debug all paths in collection
const items = await queryCollection('blog').all()
console.log(items.map(i => i.path))

// Then query with correct path
const post = await queryCollection('blog').path('/blog/hello').first()

---

Issue #8: Studio OAuth Callback Fails

Error: redirect_uri_mismatch

Source: GitHub OAuth documentation

Why It Happens: OAuth callback URL doesn't match exactly

Prevention: Ensure callback URL in GitHub OAuth app matches production domain exactly (including https://)

Solution: 1. Go to GitHub → Settings → Developer settings → OAuth Apps 2. Set Authorization callback URL to: https://yourdomain.com/api/__studio/oauth/callback 3. Must include protocol (https://) 4. Must match production domain exactly

---

Issue #9: Studio Changes Not Saving

Error: Changes in Studio don't commit to GitHub

Source: Nuxt Studio documentation

Why It Happens: GitHub token lacks write permissions or repository config incorrect

Prevention: Verify repository configuration and GitHub token permissions

Solution:

// nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    enabled: true,
    gitInfo: {
      name: 'your-name',
      email: 'your-email@example.com'
    }
  }
})

Ensure GitHub token has repo scope (full repository access).

---

Issue #10: Better-SQLite3 Module Not Found

Error: Cannot find module 'better-sqlite3'

Source: Node.js error logs

Why It Happens: Database connector not installed

Prevention: Install database connector

Solution:

bun add better-sqlite3
# or
npm install better-sqlite3

Note: This is required for Nuxt Content v3 SQL storage.

---

Issue #11: JSON File Validation Error

Error: Unexpected token [ in JSON

Source: Nuxt Content validation

Why It Happens: JSON file contains array instead of object

Prevention: Each JSON file must contain single object, not array

Solution:

// ❌ Wrong: array at root
[
  { "name": "Item 1" },
  { "name": "Item 2" }
]

// ✅ Correct: object at root
{
  "name": "Item 1",
  "description": "This is an item"
}

For arrays: Use separate JSON files or nest array inside object.

---

Issue #12: Numeric Prefix Sorting Wrong

Error: Files sort as 1, 10, 2, 3 instead of 1, 2, 3, 10

Source: File system alphabetical sorting

Why It Happens: Single-digit numbers sort alphabetically

Prevention: Use zero-padded prefixes

Solution:

# ❌ Wrong
1-introduction.md
2-setup.md
10-advanced.md

# ✅ Correct
01-introduction.md
02-setup.md
10-advanced.md

---

Issue #13: Server Query Type Error

Error: TypeScript error in server routes

Source: TypeScript compilation

Why It Happens: Missing server/tsconfig.json

Prevention: Create server/tsconfig.json extending ../.nuxt/tsconfig.server.json

Solution:

// server/tsconfig.json
{
  "extends": "../.nuxt/tsconfig.server.json"
}

---

Issue #14: Vercel Build Fails

Error: Build timeout or out of memory

Source: Vercel build logs

Why It Happens: Large content causing memory issues

Prevention: Use route rules with prerendering and pagination

Solution:

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/blog/**': { prerender: true },
    '/api/**': { cors: true }
  },
  
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: ['/'],
      ignore: ['/admin/**']
    }
  }
})

Also consider: Implement pagination for large collections.

---

Issue #15: Excerpt Not Working

Error: Excerpt returns full content

Source: Nuxt Content documentation

Why It Happens: Missing <!--more--> divider in Markdown

Prevention: Add <!--more--> in content to separate excerpt from full content

Solution:

---
title: My Post
---

This is the excerpt content. It appears in listings.

<!--more-->

This is the full content. It only appears on the full post page.

// Query with excerpt
const posts = await queryCollection('blog')
  .only(['title', 'excerpt', 'path'])
  .all()

---

Issue #16: Code Highlighting Not Working

Error: Code blocks show plain text without syntax highlighting

Source: Shiki configuration

Why It Happens: Language not specified or Shiki not configured

Prevention: Specify language in code fence

Solution:

<!-- ❌ Wrong: no language specified -->
\`\`\`
const hello = 'world'
\`\`\`

<!-- ✅ Correct: language specified -->
\`\`\`typescript
const hello: string = 'world'
\`\`\`

Configure Shiki (optional):

// nuxt.config.ts
export default defineNuxtConfig({
  content: {
    highlight: {
      theme: 'github-dark',
      langs: ['typescript', 'javascript', 'vue', 'css']
    }
  }
})

---

Issue #17: Remote Repository Auth Fails

Error: Authentication failed when using remote repository

Source: Git authentication

Why It Happens: Invalid token or missing credentials

Prevention: Store GitHub token in environment variable and reference in source.authToken

Solution:

# .env
GITHUB_TOKEN=your_github_token_here

// content.config.ts
export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: {
        repository: 'owner/repo',
        prefix: 'docs',
        authToken: process.env.GITHUB_TOKEN
      }
    })
  }
})

Token Permissions: Ensure token has repo scope for private repositories.

---

Issue #18: Prose Components Not Applied

Error: Custom Prose components don't override defaults

Source: MDC configuration

Why It Happens: Component name doesn't match exactly or not in components/content/

Prevention: Use exact names (ProseA, ProseH1, etc.) in components/content/ directory

Solution:

<!-- components/content/ProseA.vue -->
<template>
  <a :href="href" class="custom-link" target="_blank">
    <slot />
  </a>
</template>

<script setup>
defineProps<{ href: string }>()
</script>

Prose Component Names:

• ProseA - Links
• ProseH1, ProseH2, etc. - Headings
• ProseP - Paragraphs
• ProseCode - Inline code
• ProseCodeInline - Code spans
• ProseImg - Images
• ProseUl, ProseOl - Lists

---

Summary

Total Issues Documented: 18 Categories:

• Configuration: 7 issues (#1, #2, #4, #10, #13, #17, #18)
• Content Management: 6 issues (#6, #7, #11, #12, #15, #16)
• Development: 3 issues (#3, #5, #14)
• Studio Integration: 2 issues (#8, #9)

Prevention: Always follow the Quick Start guide and use proper TypeScript types for content collections.

MDC Syntax Quick Reference

Basic Component Syntax

::component-name
Default slot content
::

Example:

::alert
This is an alert!
::

---

Named Slots

::hero
Main content
#description
Description content
#actions
Action buttons
::

---

Component Props

Inline Props:

::alert{type="warning" icon="i-lucide-alert"}
Warning message
::

YAML Props:

::card
---
title: Card Title
description: Card description
icon: IconNuxt
link: /docs
---
::

---

Inline Components

:badge[New]{color="green"}
:icon{name="i-lucide-star"}

---

Attributes

# Heading {#custom-id}
Paragraph {.text-lg .font-bold}
[Link](/url){target="_blank"}
Combined {#id .class style="color: blue;"}

---

Data Binding

---
title: My Post
author: John Doe
count: 42
---

# {{ $doc.title }}
By {{ $doc.author }}
Count: {{ $doc.count }}

---

Common Components

Alert

::alert{type="info"}
Info message
::

::alert{type="warning"}
Warning message
::

::alert{type="error"}
Error message
::

Callout

::callout
Important information
::

Code Group

::code-group

export default defineNuxtConfig({})

npm run dev

::

Tabs

::tabs
#tab1
Content for tab 1
#tab2
Content for tab 2
::

---

Prose Components Override

Create in components/content/:

• ProseA.vue - Links
• ProseCode.vue - Inline code
• ProsePre.vue - Code blocks
• ProseH1.vue through ProseH6.vue - Headings
• ProseP.vue - Paragraphs
• ProseImg.vue - Images
• ProseUl.vue, ProseOl.vue, ProseLi.vue - Lists

Example (components/content/ProseA.vue):

<template>
  <a :href="href" class="custom-link">
    <slot />
  </a>
</template>

<script setup>
defineProps({ href: String })
</script>

---

Slot Unwrapping

<!-- components/content/Callout.vue -->
<template>
  <div class="callout">
    <slot mdc-unwrap="p" />
  </div>
</template>

Removes wrapping <p> tags from slot content.

Query Operators Quick Reference

SQL Operators

Equality & Comparison

// Equal to
.where('published', '=', true)

// Not equal
.where('status', '<>', 'draft')

// Greater than / Less than
.where('date', '>', '2024-01-01')
.where('price', '<', 1000)

// Greater/Less than or equal
.where('views', '>=', 100)
.where('score', '<=', 50)

List Membership

// IN operator
.where('category', 'IN', ['news', 'tutorial'])

// NOT IN
.where('status', 'NOT IN', ['draft', 'archived'])

Range

// BETWEEN
.where('date', 'BETWEEN', ['2024-01-01', '2024-12-31'])

// NOT BETWEEN
.where('price', 'NOT BETWEEN', [100, 500])

Null Checks

// IS NULL
.where('deletedAt', 'IS NULL')

// IS NOT NULL
.where('publishedAt', 'IS NOT NULL')

Pattern Matching

// LIKE (with % wildcard)
.where('title', 'LIKE', '%Nuxt%')
.where('email', 'LIKE', '%@gmail.com')

// NOT LIKE
.where('title', 'NOT LIKE', '%draft%')

---

Combining Conditions

AND Conditions (Default)

queryCollection('blog')
  .where('published', '=', true)
  .where('category', '=', 'tutorial')
  .where('date', '>', '2024-01-01')
  .all()

Grouped AND

queryCollection('blog')
  .andWhere(q =>
    q.where('date', '>', '2024-01-01')
     .where('category', '=', 'news')
  )
  .all()

OR Conditions

queryCollection('blog')
  .orWhere(q =>
    q.where('featured', '=', true)
     .where('priority', '>', 5)
  )
  .all()

Complex Conditions

queryCollection('blog')
  .where('published', '=', true)
  .andWhere(q =>
    q.where('category', '=', 'news')
     .orWhere(sub =>
       sub.where('featured', '=', true)
     )
  )
  .all()

---

Ordering

// Single field
.order('date', 'DESC')
.order('title', 'ASC')

// Multiple fields
.order('category', 'ASC')
.order('date', 'DESC')

---

Pagination

// Limit
.limit(10)

// Skip and limit
.skip(5)
.limit(10)

// Page-based
const page = 2
const perPage = 10
.skip((page - 1) * perPage)
.limit(perPage)

---

Field Selection

// Select specific fields
.select('path', 'title', 'description', 'date')

// Benefits: Smaller payload, faster queries

---

Counting

const count = await queryCollection('blog')
  .where('published', '=', true)
  .count()

---

Server-Side Queries

// Pass event as first argument
export default eventHandler(async (event) => {
  const posts = await queryCollection(event, 'blog').all()
  return posts
})

---

Complete Query Example

// Get latest 10 published tutorials from 2024,
// ordered by date, with specific fields only
const tutorials = await queryCollection('blog')
  .where('published', '=', true)
  .where('category', '=', 'tutorial')
  .where('date', '>=', '2024-01-01')
  .select('path', 'title', 'description', 'date', 'author')
  .order('date', 'DESC')
  .limit(10)
  .all()

Nuxt Studio Setup Checklist

Prerequisites

• [ ] Nuxt Content v3 installed
• [ ] GitHub account
• [ ] Production domain (for OAuth)

---

1. Install Nuxt Studio

# Bun
bun add nuxt-studio@alpha

# npm
npm install nuxt-studio@alpha

# pnpm
pnpm add nuxt-studio@alpha

---

2. Configure nuxt.config.ts

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content', 'nuxt-studio'],

  studio: {
    route: '/_studio',  // Access route

    repository: {
      provider: 'github',
      owner: 'your-username',
      repo: 'your-repo',
      branch: 'main'
    }
  }
})

---

3. Create GitHub OAuth App

Production OAuth App

1. Visit: https://github.com/settings/developers 2. Click New OAuth App 3. Fill in:

• Application name: Your App Name
• Homepage URL: https://yourdomain.com
• Authorization callback URL: https://yourdomain.com

4. Click Register application 5. Copy the Client ID 6. Click Generate a new client secret 7. Copy the Client Secret (shown only once!)

Staging OAuth App (Optional)

Create a separate OAuth app for staging:

• Application name: Your App Name (Staging)
• Homepage URL: https://staging.yourdomain.com
• Callback URL: https://staging.yourdomain.com

---

4. Set Environment Variables

Local Development

# .env
STUDIO_GITHUB_CLIENT_ID=your_client_id_here
STUDIO_GITHUB_CLIENT_SECRET=your_client_secret_here

Production (Cloudflare)

Add in Cloudflare Dashboard:

• Project → Settings → Environment Variables
• Add STUDIO_GITHUB_CLIENT_ID
• Add STUDIO_GITHUB_CLIENT_SECRET

Production (Vercel)

Add in Vercel Dashboard:

• Project → Settings → Environment Variables
• Production scope
• Add both variables

---

5. Deployment Configuration

Required

• ✅ SSR enabled (not static generation)
• ✅ Build command: nuxt build
• ✅ Server runtime support

Hybrid Rendering (Optional)

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/blog/**': { prerender: true },
    '/_studio/**': { ssr: true }  // Studio requires SSR
  }
})

---

6. Staging/Preview Setup

Environment-Based Branch

// nuxt.config.ts
studio: {
  repository: {
    provider: 'github',
    owner: 'your-username',
    repo: 'your-repo',
    branch: process.env.STUDIO_GITHUB_BRANCH_NAME || 'main'
  }
}

Environment Variables

Staging:

STUDIO_GITHUB_BRANCH_NAME=staging
STUDIO_GITHUB_CLIENT_ID=staging_client_id
STUDIO_GITHUB_CLIENT_SECRET=staging_client_secret

Production:

STUDIO_GITHUB_BRANCH_NAME=main
STUDIO_GITHUB_CLIENT_ID=production_client_id
STUDIO_GITHUB_CLIENT_SECRET=production_client_secret

---

7. Access Studio

Web Interface

https://yourdomain.com/_studio

Keyboard Shortcut

Press Ctrl + . anywhere on the site

Login Flow

1. Click "Login with GitHub" 2. Authorize OAuth app 3. Start editing!

---

8. Development Mode (Optional)

Enable local file writing:

studio: {
  development: {
    sync: true  // Writes to local content/
  },
  repository: {
    // ... config
  }
}

---

Troubleshooting

OAuth Fails

• ✅ Callback URL matches exactly (including https://)
• ✅ Environment variables set correctly
• ✅ OAuth app not suspended

Studio Not Accessible

• ✅ SSR is enabled
• ✅ Route is correct (/_studio)
• ✅ Module in modules array

Changes Not Saving

• ✅ GitHub token has write permissions
• ✅ Repository configuration correct
• ✅ Check browser console for errors

---

Complete Checklist

• [ ] Nuxt Studio installed
• [ ] Module added to nuxt.config.ts
• [ ] Repository configured
• [ ] GitHub OAuth app created (production)
• [ ] Environment variables set
• [ ] SSR enabled
• [ ] Deployed to hosting platform
• [ ] Studio accessible at /_studio
• [ ] Login works
• [ ] Changes commit to GitHub

---

Advanced: Monorepo Support

studio: {
  repository: {
    provider: 'github',
    owner: 'your-username',
    repo: 'monorepo-name',
    branch: 'main',
    rootDir: 'apps/website'  // Path to Nuxt app
  }
}