contentstack-vibe-docs（contentstack 氛围文档）

Contentstack Documentation for AI Agents

Comprehensive, AI-optimized documentation for the Contentstack CMS. This skill contains ~11,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.

Common Task Combinations

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

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 modeling guide?

• Designing content types, references, global fields, modular blocks, taxonomy, or locale strategy -> data-modeling-best-practices.md
• Need field type or platform basics first -> base-concepts.md before the modeling guide

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
• What has an independent lifecycle? — Separate content type vs inline field
• What needs reuse vs page-local composition? — Reference vs modular block
• Need references included? — .includeReference() usage
• Using modular blocks? — Rendering patterns
• Need global fields or taxonomy? — Shared schema vs classification
• 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.preview,
  },
});

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

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: