contentstack-vibe-docs

name	contentstack-vibe-docs
description	Comprehensive Contentstack CMS documentation for building web applications. Covers REST API, GraphQL API, Content Management API, Image Delivery API, TypeScript SDKs, Live Preview, OAuth authentication, and framework patterns for Next.js, Nuxt, and Gatsby. Use when implementing any Contentstack feature, fetching or managing content, setting up Live Preview, configuring regions, building CLI plugins, or creating Developer Hub apps.
license	MIT
metadata	{"author":"timbenniks","version":"2.0"}

Contentstack Documentation for AI Agents

Comprehensive, AI-optimized documentation for the Contentstack CMS. This skill contains ~10,000 lines across 20 reference files.

STOP. Do not read all reference files. Use the routing table below to read ONLY the 1-3 files relevant to your current task.

Routing Table

Match your task to the right file(s). Read the minimum set needed.

Task	Read this file	Lines
Quick code pattern lookup	QUICK_REFERENCE.md	477
Understand Contentstack basics	base-concepts.md	166
Configure regions/endpoints	regions.md	350
Fetch content (REST)	rest-api.md	487
Fetch content (GraphQL)	graphql-api.md	620
Create/update/delete/publish content	content-management-api.md	1138
Transform/optimize images	image-delivery-api.md	565
Use TypeScript Delivery SDK	delivery-sdk.md	431
Implement Live Preview	concepts.md	131
Live Preview (client-side, ssr:false)	csr-mode.md	268
Live Preview (server-side, ssr:true)	ssr-mode.md	315
Build with Next.js	nextjs.md	424
Build with Nuxt	nuxt.md	404
Build with Gatsby	gatsby.md	433
Implement OAuth login	oauth.md	906
Create CLI plugins	cli-plugins.md	1672
Build Developer Hub apps	devhub-apps.md	869
See real-world code patterns	practical-examples.md	409
Check package versions	VERSIONS.md	103

Common Task Combinations

When a task requires multiple docs, read only these combinations:

Scenario	Files to read (in order)
New Next.js project	base-concepts.md, delivery-sdk.md, nextjs.md
New Nuxt project	base-concepts.md, delivery-sdk.md, nuxt.md
Add Live Preview to Next.js	live-preview/concepts.md, live-preview/ssr-mode.md, nextjs.md
Add Live Preview to Nuxt	live-preview/concepts.md, live-preview/csr-mode.md, nuxt.md
Build a content pipeline (CRUD)	content-management-api.md
Responsive image optimization	image-delivery-api.md
Full-stack with auth	delivery-sdk.md, nextjs.md, oauth.md
Content migration script	content-management-api.md, regions.md
Quick code snippet	QUICK_REFERENCE.md (this alone is usually enough)

Decision Helpers

Which API to use?

• Reading published content for a website/app -> REST API or GraphQL API or Delivery SDK
• Creating, updating, deleting, or publishing content -> Content Management API
• Transforming images (resize, crop, format) -> Image Delivery API

Which SDK?

• @contentstack/delivery-sdk — reading content (frontend/backend)
• @contentstack/management — writing content (backend only, never in frontend)

Which Live Preview mode?

Important: The ssr setting controls how preview updates work inside the CMS iframe, NOT your website's rendering strategy.

• ssr: false: Uses postMessage. CMS sends data changes to iframe, client JS re-fetches and updates UI instantly (no page refresh)
• ssr: true: CMS refreshes the iframe with query params (?live_preview=hash&entry_uid=...). Server reads params and fetches preview data

Security: Credentials Handling

NEVER ask the developer to share API keys, tokens, or secrets in the conversation. Always use environment variable references (process.env.CONTENTSTACK_API_KEY, etc.) in code. Never output, log, or hardcode actual credential values. If the developer pastes a real token, warn them and suggest they rotate it.

Questions to Ask Developers First

Basic Setup

• What Contentstack region? (US, EU, AU, Azure, GCP) — Required for endpoints
• Do you have credentials set up? (API Key, Delivery Token, Preview Token as environment variables — do NOT ask for the actual values)
• What environment? (production, staging, preview)

Framework & Architecture

• What framework? (Next.js, Nuxt, Gatsby, React, Vue)
• Does your site fetch data client-side or server-side? — Determines Live Preview SDK mode
• What's the hosting? (Vercel, Netlify, self-hosted)

Content Requirements

• What content types? — Query patterns
• Need references included? — .includeReference() usage
• Using modular blocks? — Rendering patterns
• Multiple locales? — Locale handling
• Need image transforms? — Image Delivery API

Authentication

• Need user login? — OAuth implementation with Contentstack
• What framework? — OAuth guide available for Next.js with Auth.js
• Session storage? — Cookie-based (JWT) or database-persisted

Implementation Workflow

1. Gather requirements — Ask questions above
2. Read relevant docs — Use routing table, start with concepts if new
3. Check examples — Find matching patterns in QUICK_REFERENCE.md
4. Implement step-by-step — Follow patterns exactly
5. Add error handling — Always try-catch
6. Use environment variables — Never hardcode credentials
7. Test thoroughly — Verify with real stack

Red Flags

Never do these:

• Ask the developer for actual API keys, tokens, or secrets — always reference process.env.* variables
• Output, log, or echo credential values in code, scripts, or responses
• Hardcode API keys or tokens — use environment variables
• Commit .env files or credentials to version control
• Use Management Tokens in frontend code — server-side only
• Read all reference files — pick only what you need
• Skip error handling
• Mix Delivery SDK patterns with Management SDK patterns
• Mix REST and GraphQL patterns incorrectly
• Forget to include references when needed

Quick Start: Stack Initialization

The most common pattern — initialize the Contentstack SDK:

// lib/contentstack.ts
import contentstack from "@contentstack/delivery-sdk";
import { getContentstackEndpoints } from "@timbenniks/contentstack-endpoints";

const endpoints = getContentstackEndpoints(
  process.env.CONTENTSTACK_REGION || "us",
  true // omitHttps = true (needed for SDK host parameter)
);

export const stack = contentstack.stack({
  apiKey: process.env.CONTENTSTACK_API_KEY!,
  deliveryToken: process.env.CONTENTSTACK_DELIVERY_TOKEN!,
  environment: process.env.CONTENTSTACK_ENVIRONMENT!,
  region: process.env.CONTENTSTACK_REGION || "us",
  live_preview: {
    enable: true,
    preview_token: process.env.CONTENTSTACK_PREVIEW_TOKEN,
    host: endpoints.contentPreview,
  },
});

Basic Content Fetching

// Fetch a single entry
const entry = await stack.contentType("blog_post").entry("entry_uid").fetch();

// Fetch all entries of a type
const entries = await stack
  .contentType("blog_post")
  .entry()
  .query()
  .find();

// Fetch with references included
const entry = await stack
  .contentType("blog_post")
  .entry("entry_uid")
  .includeReference(["author", "category"])
  .fetch();

Environment Variables Template

CONTENTSTACK_API_KEY=your_api_key
CONTENTSTACK_DELIVERY_TOKEN=your_delivery_token
CONTENTSTACK_PREVIEW_TOKEN=your_preview_token
CONTENTSTACK_ENVIRONMENT=production
CONTENTSTACK_REGION=us

Region Quick Reference

Region Code	Provider	Content Delivery Host
us	AWS	cdn.contentstack.io
eu	AWS	eu-cdn.contentstack.com
au	AWS	au-cdn.contentstack.com
azure-na	Azure	azure-na-cdn.contentstack.com
azure-eu	Azure	azure-eu-cdn.contentstack.com
gcp-na	GCP	gcp-na-cdn.contentstack.com
gcp-eu	GCP	gcp-eu-cdn.contentstack.com

Use the @timbenniks/contentstack-endpoints package instead of hardcoding these — see regions.md for full details.

Reference Directory

The references/ directory contains detailed documentation organized by topic:

Directory	Contents
references/api/	REST, GraphQL, Content Management, and Image Delivery API docs
references/sdk/	TypeScript Delivery SDK guide
references/concepts/	CMS fundamentals and region configuration
references/frameworks/	Next.js, Nuxt, and Gatsby integration patterns
references/live-preview/	Live Preview concepts, CSR mode, and SSR mode
references/authentication/	OAuth with Auth.js for Next.js
references/extensions/	CLI plugin development and Developer Hub apps
references/examples/	Real-world code patterns
references/QUICK_REFERENCE.md	Condensed code patterns for quick lookup
references/VERSIONS.md	Package version compatibility