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.2 for reference publishing.
- Forgetting
.includeReference() then wondering why references are undefined.
- Ignoring
X-RateLimit-Reset and busy-looping on 429s.
1---2name: contentstack-vibe-docs3description: Comprehensive Contentstack CMS documentation for building web applications. Covers REST API, GraphQL API, Content Management API, Image Delivery API, TypeScript SDKs, Live Preview, Visual Builder, OAuth authentication, data modeling, webhooks, releases, workflows, branches, roles, localization, variants/personalization, Launch deployments, and framework patterns for Next.js, Nuxt, and Gatsby. Use when implementing any Contentstack feature.4license: MIT5---67# Contentstack Documentation for AI Agents89This 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.1011## Routing table1213| Task | File |14|------|------|15| Quick code pattern lookup | [QUICK_REFERENCE.md](references/QUICK_REFERENCE.md) |16| Contentstack basics | [concepts/base-concepts.md](references/concepts/base-concepts.md) |17| Design content models, choose references vs modular blocks vs global fields, taxonomy | [concepts/data-modeling-best-practices.md](references/concepts/data-modeling-best-practices.md) |18| Localization, fallback chains, non-localizable fields | [concepts/localization.md](references/concepts/localization.md) |19| Regions, endpoints, region-aware hosts | [concepts/regions.md](references/concepts/regions.md) |20| Fetch content (REST) | [api/rest-api.md](references/api/rest-api.md) |21| Fetch content (GraphQL) | [api/graphql-api.md](references/api/graphql-api.md) |22| Create/update/delete/publish, modular block schema, CMA headers | [api/content-management-api.md](references/api/content-management-api.md) |23| Transform images, asset folders, asset limits, file_uid | [api/image-delivery-api.md](references/api/image-delivery-api.md) |24| TypeScript Delivery SDK | [sdk/delivery-sdk.md](references/sdk/delivery-sdk.md) |25| Live Preview overview | [live-preview/concepts.md](references/live-preview/concepts.md) |26| Live Preview CSR (`ssr: false`) | [live-preview/csr-mode.md](references/live-preview/csr-mode.md) |27| Live Preview SSR (`ssr: true`), per-request factory, hash isolation | [live-preview/ssr-mode.md](references/live-preview/ssr-mode.md) |28| Visual Builder, edit tags, `addEditableTags`, `VB_EmptyBlockParentClass` | [live-preview/visual-builder.md](references/live-preview/visual-builder.md) |29| Debug Live Preview / Visual Builder failures | [live-preview/debugging.md](references/live-preview/debugging.md) |30| Next.js patterns, Draft Mode, `revalidateTag` | [frameworks/nextjs.md](references/frameworks/nextjs.md) |31| Nuxt patterns | [frameworks/nuxt.md](references/frameworks/nuxt.md) |32| Gatsby patterns | [frameworks/gatsby.md](references/frameworks/gatsby.md) |33| Pick the right token (delivery/preview/management/authtoken/OAuth) | [security/tokens-authentication.md](references/security/tokens-authentication.md) |34| Roles, custom permissions, teams | [security/roles-permissions.md](references/security/roles-permissions.md) |35| OAuth login with Auth.js v5 (Next.js) | [authentication/oauth.md](references/authentication/oauth.md) |36| Webhooks: signatures, event channels, release storms | [workflows/webhooks.md](references/workflows/webhooks.md) |37| Releases: atomic coordinated deploys | [workflows/releases.md](references/workflows/releases.md) |38| Workflows & publish rules | [workflows/content-workflows.md](references/workflows/content-workflows.md) |39| Branches & aliases: zero-downtime deploys | [workflows/branches-aliases.md](references/workflows/branches-aliases.md) |40| Environments, publishing, Sync API, rate limits | [workflows/environments-publishing.md](references/workflows/environments-publishing.md) |41| Variants & Personalize | [personalization/variants-and-personalize.md](references/personalization/variants-and-personalize.md) |42| CLI plugins — overview & quickstart | [extensions/cli-plugins/overview.md](references/extensions/cli-plugins/overview.md) |43| CLI plugins — commands, flags, arguments | [extensions/cli-plugins/commands.md](references/extensions/cli-plugins/commands.md) |44| CLI plugins — publishing, testing, troubleshooting | [extensions/cli-plugins/publishing.md](references/extensions/cli-plugins/publishing.md) |45| Developer Hub apps (App SDK, UI locations, API proxy) | [extensions/devhub-apps.md](references/extensions/devhub-apps.md) |46| Contentstack Launch: deployments, env sync | [extensions/launch.md](references/extensions/launch.md) |47| Real-world code patterns | [examples/practical-examples.md](references/examples/practical-examples.md) |48| Package versions | [VERSIONS.md](references/VERSIONS.md) |4950## Common task combinations5152| Scenario | Files (in order) |53|----------|------------------|54| New Next.js project | base-concepts → delivery-sdk → nextjs |55| New Nuxt project | base-concepts → delivery-sdk → nuxt |56| Add Live Preview to Next.js | live-preview/concepts → live-preview/ssr-mode → nextjs |57| Add Visual Builder to existing site | live-preview/visual-builder |58| Debug broken preview | live-preview/debugging |59| Build a CRUD/migration script | content-management-api → security/tokens-authentication |60| Full-stack with user login | delivery-sdk → nextjs → oauth |61| Webhook-driven rebuild | workflows/webhooks → workflows/environments-publishing |62| Zero-downtime content deploy | workflows/branches-aliases → workflows/releases |63| Multi-locale rollout | concepts/localization → workflows/environments-publishing |64| Deploy to Launch from CI | extensions/launch → workflows/webhooks |65| Responsive image optimization | api/image-delivery-api |66| Quick snippet | QUICK_REFERENCE.md |6768## Decision helpers6970**Which API?**71Read published content → REST / GraphQL / Delivery SDK. Write content → Content Management API. Transform images → Image Delivery API.7273**Which SDK?**74`@contentstack/delivery-sdk` for reads (frontend/backend). `@contentstack/management` for writes (server-only, never frontend).7576**Which Live Preview mode?**77The `ssr` flag controls how the CMS iframe updates, not your app's rendering strategy.78- `ssr: false` — postMessage. CMS sends data to iframe, client re-fetches and updates without reload.79- `ssr: true` — iframe reload with `?live_preview=<hash>&entry_uid=...`. Server reads params per request.8081For `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`.8283**Which token?**84Frontend 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`.8586## Ask before coding8788Before implementing, confirm with the developer:8990- **Region** (US, EU, AU, Azure NA/EU, GCP NA/EU) — affects every endpoint.91- **Framework** (Next.js, Nuxt, Gatsby, etc.) — determines Live Preview mode.92- **Environment** (dev/staging/production) — scopes the delivery token.93- **Credentials in env vars?** — never ask for the values themselves.9495## Security (summary)9697Never 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`.9899## Red flags100101- Reading all reference files instead of routing to 1-3.102- Hardcoding credentials or exposing management tokens to the browser.103- Hardcoding region hosts instead of using `@timbenniks/contentstack-endpoints`.104- Mixing Delivery SDK patterns with Management SDK patterns.105- Mixing REST and GraphQL patterns in one query.106- Sharing a module-level Contentstack client across SSR preview requests.107- Forgetting `api_version: 3.2` for reference publishing.108- Forgetting `.includeReference()` then wondering why references are undefined.109- Ignoring `X-RateLimit-Reset` and busy-looping on 429s.
contentstack