contentstack-vibe-docs
Contentstack Documentation for AI Agents
This skill contains ~13,500 lines across 30+ reference files. Read the routing table, pick the 1-3 files you actually need, and stop. Never read everything.
Routing table
| Task | File |
|---|---|
| Quick code pattern lookup | QUICK_REFERENCE.md |
| Contentstack basics | concepts/base-concepts.md |
| Design content models, choose references vs modular blocks vs global fields, taxonomy | concepts/data-modeling-best-practices.md |
| Localization, fallback chains, non-localizable fields | concepts/localization.md |
| Regions, endpoints, region-aware hosts | concepts/regions.md |
| Fetch content (REST) | api/rest-api.md |
| Fetch content (GraphQL) | api/graphql-api.md |
| Create/update/delete/publish, modular block schema, CMA headers | api/content-management-api.md |
| Transform images, asset folders, asset limits, file_uid | api/image-delivery-api.md |
| TypeScript Delivery SDK | sdk/delivery-sdk.md |
| Live Preview overview | live-preview/concepts.md |
Live Preview CSR (ssr: false) |
live-preview/csr-mode.md |
Live Preview SSR (ssr: true), per-request factory, hash isolation |
live-preview/ssr-mode.md |
Visual Builder, edit tags, addEditableTags, VB_EmptyBlockParentClass |
live-preview/visual-builder.md |
| Debug Live Preview / Visual Builder failures | live-preview/debugging.md |
Next.js patterns, Draft Mode, revalidateTag |
frameworks/nextjs.md |
| Nuxt patterns | frameworks/nuxt.md |
| Gatsby patterns | frameworks/gatsby.md |
| Pick the right token (delivery/preview/management/authtoken/OAuth) | security/tokens-authentication.md |
| Roles, custom permissions, teams | security/roles-permissions.md |
| OAuth login with Auth.js v5 (Next.js) | authentication/oauth.md |
| Webhooks: signatures, event channels, release storms | workflows/webhooks.md |
| Releases: atomic coordinated deploys | workflows/releases.md |
| Workflows & publish rules | workflows/content-workflows.md |
| Branches & aliases: zero-downtime deploys | workflows/branches-aliases.md |
| Environments, publishing, Sync API, rate limits | workflows/environments-publishing.md |
| Variants & Personalize | personalization/variants-and-personalize.md |
| CLI plugins — overview & quickstart | extensions/cli-plugins/overview.md |
| CLI plugins — commands, flags, arguments | extensions/cli-plugins/commands.md |
| CLI plugins — publishing, testing, troubleshooting | extensions/cli-plugins/publishing.md |
| Developer Hub apps (App SDK, UI locations, API proxy) | extensions/devhub-apps.md |
| Contentstack Launch: deployments, env sync | extensions/launch.md |
| Real-world code patterns | examples/practical-examples.md |
| Package versions | VERSIONS.md |
Common task combinations
| Scenario | Files (in order) |
|---|---|
| New Next.js project | base-concepts → delivery-sdk → nextjs |
| New Nuxt project | base-concepts → delivery-sdk → nuxt |
| Add Live Preview to Next.js | live-preview/concepts → live-preview/ssr-mode → nextjs |
| Add Visual Builder to existing site | live-preview/visual-builder |
| Debug broken preview | live-preview/debugging |
| Build a CRUD/migration script | content-management-api → security/tokens-authentication |
| Full-stack with user login | delivery-sdk → nextjs → oauth |
| Webhook-driven rebuild | workflows/webhooks → workflows/environments-publishing |
| Zero-downtime content deploy | workflows/branches-aliases → workflows/releases |
| Multi-locale rollout | concepts/localization → workflows/environments-publishing |
| Deploy to Launch from CI | extensions/launch → workflows/webhooks |
| Responsive image optimization | api/image-delivery-api |
| Quick snippet | QUICK_REFERENCE.md |
Decision helpers
Which API? Read published content → REST / GraphQL / Delivery SDK. Write content → Content Management API. Transform images → Image Delivery API.
Which SDK?
@contentstack/delivery-sdk for reads (frontend/backend). @contentstack/management for writes (server-only, never frontend).
Which Live Preview mode?
The ssr flag controls how the CMS iframe updates, not your app's rendering strategy.
ssr: false— postMessage. CMS sends data to iframe, client re-fetches and updates without reload.ssr: true— iframe reload with?live_preview=<hash>&entry_uid=.... Server reads params per request.
For ssr: true, create a fresh Contentstack client per request (factory pattern). Sharing one global client leaks preview state between concurrent editors. See live-preview/ssr-mode.md.
Which token?
Frontend reads → Delivery Token (safe). Preview reads → Preview Token (safe). Server writes → Management Token (NEVER frontend). User sessions → Authtoken or OAuth. Full decision tree in security/tokens-authentication.md.
Ask before coding
Before implementing, confirm with the developer:
- Region (US, EU, AU, Azure NA/EU, GCP NA/EU) — affects every endpoint.
- Framework (Next.js, Nuxt, Gatsby, etc.) — determines Live Preview mode.
- Environment (dev/staging/production) — scopes the delivery token.
- Credentials in env vars? — never ask for the values themselves.
Security (summary)
Never ask for, log, output, or hardcode API keys, tokens, or secrets. Always use process.env.* references. Never use Management Tokens in frontend code. If a developer pastes a real token, warn them and recommend rotating it. Full rules: security/tokens-authentication.md.
Red flags
- Reading all reference files instead of routing to 1-3.
- Hardcoding credentials or exposing management tokens to the browser.
- Hardcoding region hosts instead of using
@timbenniks/contentstack-endpoints. - Mixing Delivery SDK patterns with Management SDK patterns.
- Mixing REST and GraphQL patterns in one query.
- Sharing a module-level Contentstack client across SSR preview requests.
- Forgetting
api_version: 3.2for reference publishing. - Forgetting
.includeReference()then wondering why references are undefined. - Ignoring
X-RateLimit-Resetand busy-looping on 429s.