Contentstack Vibe Docs

Comprehensive Contentstack CMS documentation for AI coding agents. Routes to the right reference for REST/GraphQL/CMA/Image Delivery APIs, TypeScript SDKs, Live Preview (CSR + SSR), OAuth with Auth.js, regions, frameworks (Next.js, Nuxt, Gatsby), CLI plugins, and Developer Hub apps. Use when implementing or fetching Contentstack content, configuring Live Preview, setting up regions, or building extensions.

---
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, 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.
license: MIT
metadata:
  author: timbenniks
  version: "2.1"
---

# 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](references/QUICK_REFERENCE.md) |
| Contentstack basics | [concepts/base-concepts.md](references/concepts/base-concepts.md) |
| 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) |
| Localization, fallback chains, non-localizable fields | [concepts/localization.md](references/concepts/localization.md) |
| Regions, endpoints, region-aware hosts | [concepts/regions.md](references/concepts/regions.md) |
| Fetch content (REST) | [api/rest-api.md](references/api/rest-api.md) |
| Fetch content (GraphQL) | [api/graphql-api.md](references/api/graphql-api.md) |
| Create/update/delete/publish, modular block schema, CMA headers | [api/content-management-api.md](references/api/content-management-api.md) |
| Transform images, asset folders, asset limits, file_uid | [api/image-delivery-api.md](references/api/image-delivery-api.md) |
| TypeScript Delivery SDK | [sdk/delivery-sdk.md](references/sdk/delivery-sdk.md) |
| Live Preview overview | [live-preview/concepts.md](references/live-preview/concepts.md) |
| Live Preview CSR (`ssr: false`) | [live-preview/csr-mode.md](references/live-preview/csr-mode.md) |
| Live Preview SSR (`ssr: true`), per-request factory, hash isolation | [live-preview/ssr-mode.md](references/live-preview/ssr-mode.md) |
| Visual Builder, edit tags, `addEditableTags`, `VB_EmptyBlockParentClass` | [live-preview/visual-builder.md](references/live-preview/visual-builder.md) |
| Debug Live Preview / Visual Builder failures | [live-preview/debugging.md](references/live-preview/debugging.md) |
| Next.js patterns, Draft Mode, `revalidateTag` | [frameworks/nextjs.md](references/frameworks/nextjs.md) |
| Nuxt patterns | [frameworks/nuxt.md](references/frameworks/nuxt.md) |
| Gatsby patterns | [frameworks/gatsby.md](references/frameworks/gatsby.md) |
| Pick the right token (delivery/preview/management/authtoken/OAuth) | [security/tokens-authentication.md](references/security/tokens-authentication.md) |
| Roles, custom permissions, teams | [security/roles-permissions.md](references/security/roles-permissions.md) |
| OAuth login with Auth.js v5 (Next.js) | [authentication/oauth.md](references/authentication/oauth.md) |
| Webhooks: signatures, event channels, release storms | [workflows/webhooks.md](references/workflows/webhooks.md) |
| Releases: atomic coordinated deploys | [workflows/releases.md](references/workflows/releases.md) |
| Workflows & publish rules | [workflows/content-workflows.md](references/workflows/content-workflows.md) |
| Branches & aliases: zero-downtime deploys | [workflows/branches-aliases.md](references/workflows/branches-aliases.md) |
| Environments, publishing, Sync API, rate limits | [workflows/environments-publishing.md](references/workflows/environments-publishing.md) |
| Variants & Personalize | [personalization/variants-and-personalize.md](references/personalization/variants-and-personalize.md) |
| CLI plugins — overview & quickstart | [extensions/cli-plugins/overview.md](references/extensions/cli-plugins/overview.md) |
| CLI plugins — commands, flags, arguments | [extensions/cli-plugins/commands.md](references/extensions/cli-plugins/commands.md) |
| CLI plugins — publishing, testing, troubleshooting | [extensions/cli-plugins/publishing.md](references/extensions/cli-plugins/publishing.md) |
| Developer Hub apps (App SDK, UI locations, API proxy) | [extensions/devhub-apps.md](references/extensions/devhub-apps.md) |
| Contentstack Launch: deployments, env sync | [extensions/launch.md](references/extensions/launch.md) |
| Real-world code patterns | [examples/practical-examples.md](references/examples/practical-examples.md) |
| Package versions | [VERSIONS.md](references/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.

Always-on routing table, decision helpers, security guardrails, and quick patterns for Contentstack work. Points the agent at the contentstack-vibe-docs skill for full references.

---
description: Contentstack vibe-docs skill — routing, patterns, and conventions for AI-assisted Contentstack development
alwaysApply: true
---

# Contentstack Vibe Docs

This repo is an AI agent skill. The full routing table, decision helpers, and task combinations live in [`skills/contentstack-vibe-docs/SKILL.md`](skills/contentstack-vibe-docs/SKILL.md). **Read that first.** The skill has ~13,500 lines across 34 reference files — never read them all. Route to 1-3 files per task.

Reference files live at `skills/contentstack-vibe-docs/references/`.

## Security — non-negotiable

- Never ask for, output, log, or hardcode API keys, tokens, or secrets.
- Always use `process.env.*` in code.
- Never commit `.env` files.
- Management Tokens are **server-side only** — never in frontend code or public env vars (`NEXT_PUBLIC_*`, `NUXT_PUBLIC_*`).
- Delivery Tokens and Preview Tokens are client-safe; Management Tokens are not.
- If a developer pastes a real token in the conversation, warn them and recommend rotation.

Full decision tree: `skills/contentstack-vibe-docs/references/security/tokens-authentication.md`.

## Red flags

- Reading all reference files instead of routing to the right 1-3.
- Hardcoding region endpoints — use `@timbenniks/contentstack-endpoints`.
- Sharing a module-level Contentstack client across SSR preview requests — use a per-request factory (see `skills/contentstack-vibe-docs/references/live-preview/ssr-mode.md`).
- Calling `.includeReference()` on `.query()` — correct chain: `entry().includeReference([...]).query().find()`.
- Using `.descending()` / `.ascending()` — correct: `.orderByDescending()` / `.orderByAscending()`.
- `QueryOperation.NOT_EQUAL` / `GREATER_THAN` — correct: `NOT_EQUALS` / `IS_GREATER_THAN`.
- Enum/dropdown fields without `display_type: "dropdown"` — CMA rejects.
- `is_page: true` without a `url` field in the schema — CMA rejects and Visual Builder can't route.
- Mixing REST and GraphQL patterns, or Delivery SDK patterns with Management SDK patterns, in one call.
- `Contentstack.Stack()` (v3 style) instead of `contentstack.stack()` (v4+).
- Ignoring `X-RateLimit-Reset` and busy-looping on 429s.

## Ask before coding

- **Region?** (US / EU / AU / Azure NA-EU / GCP NA-EU) — every endpoint depends on this.
- **Credentials in env vars?** (never ask for actual values).
- **Framework?** (Next.js / Nuxt / Gatsby / other).
- **Data fetched server-side or client-side?** — determines Live Preview mode.