# Contentstack Studio

> Studio is the visual composition layer for your component library. Engineers register your existing React components once; from then on, anyone composes them into pages — drag, bind real CMS content, publish — without writing code or shipping a deploy. Complements the existing stack (component library, Delivery SDK, CI/CD, CMS workflow) — does NOT replace any of them.

## Start here

- **[Zero to first page walkthrough](00-getting-started/quickstart-setup.md): the recommended starting point — 30 minutes from absolute zero (no stack, no Studio, no app) to a working composition at a real URL, with each step a single LLM prompt**
- [Studio Docs landing](index.md): table of contents + role-based paths
- [Video walkthroughs](05-videos/index.md): six recorded walkthroughs (~34 min) mirroring the Getting Started guides — one for content authors, five for developers in a fixed order. Video has no transcript here, so the written guides remain the complete source
- [What is Studio](00-overview/contentstack-studio-overview.md): the visual composition layer for your component library — Section + Template as the two building blocks
- [The development flow](00-overview/the-development-flow-with-and-without-studio.md): side-by-side comparison of dev flow without and with Studio
- [When to use Templates vs Sections](00-overview/choosing-between-templates-and-sections.md): decision tree
- [Enterprise vs quickstart paths](00-overview/choosing-your-studio-setup-path.md): pick the right onboarding path

## Setup

- [Setup overview](10-setup/setup-overview.md): the two layers and reading order
- [Prerequisites](10-setup/app-prerequisites/prerequisites.md): stack-side credentials and tools you need before installing
- [Install the Delivery SDK](10-setup/app-prerequisites/install-the-delivery-sdk.md): reads published content
- [Install Live Preview](10-setup/app-prerequisites/install-live-preview.md): real-time updates into your site
- [Install the Studio SDK](10-setup/app-prerequisites/install-the-studio-sdk.md): the self-contained Studio SDK chapter — install + init + register + fetch + mount
- [CSR vs SSR](10-setup/app-prerequisites/choosing-between-csr-and-ssr-rendering.md): render strategy per framework + the searchQuery requirement
- [Create a Studio project](10-setup/studio-project/01-create-project.md): link Studio to your stack
- [Playground Canvas](10-setup/studio-project/try-studio-in-the-playground-canvas-without-an-app.md): Studio-hosted iframe for projects with no Canvas URL — try Studio without setting up a canvas-app; deploy is disabled in this mode
- [Configure environment + language + canvas URL](10-setup/studio-project/configure-environment-language-and-canvas-url.md): setting a Canvas URL graduates the project from Playground to Website Canvas
- [Add the section preview route](10-setup/studio-project/section-preview-route.md): mount `<StudioCanvas />`
- [Wire template preview routes](10-setup/studio-project/template-preview-routes.md): mount `<StudioComponent />`
- [Verify end to end](10-setup/verify-end-to-end.md): layered smoke test
- [Troubleshoot](10-setup/troubleshoot-common-studio-issues.md): common failures + fixes
- [Layer 2 runbook](10-setup/manually-configuring-the-studio-web-app.md): the human-only Studio web steps after Layer 1 (code) is done — what an LLM/CLI can vs can't do

## Bring your own components

- [BYOC overview](20-bring-your-own-components/overview.md): register your component library so Studio uses your components, not its defaults
- [Registering components](20-bring-your-own-components/register-components.md): registerComponent / registerComponents / registerLazyComponent
- [Component schema](20-bring-your-own-components/component-schema-prop-types.md): all prop types with options
- [Default data](20-bring-your-own-components/set-component-default-data.md): what renders before binding
- [Optimizing load](20-bring-your-own-components/optimizing-load-with-lazy-registration.md): lazy registration + bundle impact
- [Design tokens](20-bring-your-own-components/studio-design-tokens-overview.md): map your design system tokens
- [Studio CLI](70-cli/index.md): csdx plugin for scripted registration, Figma sync, token import
- [Figma copy/paste](20-bring-your-own-components/copy-and-paste-from-figma-to-studio.md): author flow
- [Figma generate components](20-bring-your-own-components/generate-components-from-figma.md): agentic CLI flow
- [Testing your components](20-bring-your-own-components/testing-your-components.md)
- [Publishing the library](20-bring-your-own-components/publishing-the-component-library.md): share across projects

## Bring your own data

- [BYOD overview](25-bring-your-own-data/overview.md): the two ways to render / bind data you already hold, and how they relate to the StudioComponent data prop
- [StudioComposition](25-bring-your-own-data/studio-composition.md): render a composition (page or standalone section) against a context object you supply — no SDK data fetch, no hook; CSR + SSR; spec prefetch via sdk.fetchComposition or client-side compositionUid; loop a section per array element
- [Slot data](25-bring-your-own-data/slot-data.md): wrap a slot value in `<Slot data={...}>` so dropped children bind it via component_props, nearest slot wins
- [Troubleshoot Bring Your Own Data](25-bring-your-own-data/troubleshooting.md): every error StudioComposition / sdk.fetchComposition / Slot throws with its fix — missing spec+compositionUid, SDK not initialized, unregistered components, composition not found, blank bound nodes from a context shape mismatch, RSC serialization, slot keys missing from the picker

## Composition concepts

- [Composition](30-composition/what-is-a-composition.md): the core authoring primitive
- [Canvas URL](30-composition/canvas-url.md): project-level path for section preview
- [CMS Binding](30-composition/bind-cms-content-to-studio-components.md): how component props pull data from Contentstack
- [Design Panel](33-freeform/style-components-with-the-design-panel.md): right-panel styling controls
- [Layers](30-composition/navigate-and-use-the-layers-tab.md): left-panel layer tree
- [Save vs Deploy](30-composition/save-vs-deploy-a-composition.md): publishing cycle
- [Templates](31-templates/overview.md): pages connected to a content type
- [Connected content type](31-templates/connected-content-type.md): URL derivation, the Edit URL modal
- [Using sections and components in templates](31-templates/using-sections-and-components-in-a-template.md)
- [Sections](32-sections/overview.md): reusable blocks
- [Binding to CMS](32-sections/binding-to-cms.md): linked schema, multi-schema, structural matching
- [Auto-binding](32-sections/binding-to-cms.md): scope-aware drop behaviour
- [Expose Section Props](32-sections/expose-section-props.md): per-instance overrides

## Smart Containers

- [Smart Containers overview](34-smart-containers/overview.md): containers that bind structure to data shape
- [Repeaters](34-smart-containers/create-repeatable-content-with-repeaters.md): render the same shape once per item in a list
- [Condition Blocks](34-smart-containers/condition-blocks.md): different designs per item type
- [Section Slots](34-smart-containers/section-slots.md): chainable and recursive
- [Modular Blocks](34-smart-containers/rendering-modular-block-fields.md): author-selectable block variants
- [References](34-smart-containers/rendering-reference-fields.md): bind referenced entries into structure

## Optional — Freeform

- [Freeform](33-freeform/overview.md): opt-in project feature. See the chapter for details.

## Recipes (end-to-end walkthroughs)

- **[Zero to first page](00-getting-started/quickstart-setup.md): the recommended starting point — 30 minutes from no stack / no Studio / no app to a working composition at a real URL, every step a single skill prompt**
- [Marketing site — three scenarios end-to-end](40-recipes/marketing-site-walkthrough-with-four-end-to-end-scenarios.md): the realistic shape this entire doc set is built around — Blog Post, Product Page, Case Study
- [Enterprise day one](40-recipes/enterprise-setup-from-install-to-first-authored-page.md): install → register YOUR components → first authored template
- [First template in 5 minutes](00-getting-started/quickstart-with-skills.md): evaluator quickstart
- [Card grid with slots](40-recipes/card-grid-with-slots.md): the List + Slot pattern, full build
- [Multi-schema section](40-recipes/multi-schema-sections-for-multiple-content-types.md): one section across multiple content types
- [Overrides without forking](40-recipes/per-page-component-overrides-without-forking.md): Expose Section Props in practice
- [Migrate hand-coded pages to Studio](40-recipes/migrating-hand-coded-pages-to-studio.md): per-route incremental migration playbook — paired with the `migrate-page-to-studio` skill
- [Add Studio to a Visual Editor app](40-recipes/add-studio-to-a-visual-editor-app.md): additive recipe for teams already on Visual Editor — Studio and VE are separate products that coexist (VE handles inline field editing, Studio handles page composition); VE users never migrate
- [Detect the Studio canvas / gate third-party scripts](40-recipes/detect-the-studio-canvas.md): stable editor-mode contract — `isStudioCanvas()` / `isStudioEditorMode()` from `@contentstack/studio-react`, `cs-composable-studio` query param, `cs-studio-canvas` html class, `window.__CS_STUDIO_MODE__` — gate cookie banners, chat widgets, GTM/analytics/pixels out of author sessions

## Advanced topics — production, scale, edges

- [Advanced chapter overview](50-advanced/production-deployment-edge-cases.md): when to read each page
- [Performance + bundle-size playbook](50-advanced/performance-and-bundle-size-optimization.md): claw back the weight Studio adds
- [Multi-locale at scale](50-advanced/managing-multiple-locales-at-scale.md): URL patterns, fallback chains, region-specific compositions
- [Variant aliases — deep dive](50-advanced/variant-aliases-deep-dive.md): A/B, personalisation, seasonal variants
- [SSR streaming patterns](50-advanced/ssr-streaming-patterns.md): Next App Router, Remix defer, Astro islands
- [Editorial workflow at scale](50-advanced/editorial-workflow.md): roles, approvals, scheduled publishing, environment promotion
- [Testing strategies](50-advanced/testing-strategies-for-studio-rendered-pages.md): five-layer testing model
- [Production deployment edges](50-advanced/production-deployment-edge-cases.md): ISR, CDN invalidation, edge runtime, monorepo

## Studio CLI

- [Studio CLI](70-cli/index.md): the `csdx studio` plugin — install, one-time setup (region/login/project), and the command table linking each command's page
- [Generate a Section](70-cli/section-create.md): `studio:section:create` — match a component to a content type, add wrapper sections for deeply-nested matches, and make inner components composable via `<Slot>`
- [Command reference](70-cli/command-reference.md): usage and flags for every command — [project:set](70-cli/command-reference.md#set-the-active-project) · [project:get](70-cli/command-reference.md#show-the-active-project) · [component:add](70-cli/command-reference.md#add-a-component-from-figma) · [component:register](70-cli/command-reference.md#register-local-components) · [component:sync](70-cli/command-reference.md#sync-a-component-to-the-figma-plugin) · [design-token:add](70-cli/command-reference.md#add-design-tokens) · [design-token:config](70-cli/command-reference.md#update-design-token-config) · [responsive-options:sync](70-cli/command-reference.md#sync-responsive-breakpoints)

## Reference

- [`<StudioComponent />` props — full enumeration](90-reference/composition-rendering-reference.md): the two props (specOptions, data), the CompositionQuery shapes, CompositionQueryOptions (variantAlias, locale, templateEntryUid, extendQuery, custom fetchers), all line-mapped to SDK types
- [`<StudioComposition />` props](25-bring-your-own-data/studio-composition-props-reference.md): the context/spec/compositionUid/loadingFallback/errorFallback props + the spec-only sdk.fetchComposition fetcher (bring-your-own-data)
- [`<Slot>` props](25-bring-your-own-data/slot-props-reference.md): data + children, shallow nearest-wins merge into component_props for slot children
- [URL variables](90-reference/url-variables-reference.md): every variable usable in composition URL patterns
- [Linked-schema matching rules](90-reference/linked-schema-matching-rules.md): structural matching algorithm in detail
- [Feature flags](90-reference/control-features-with-feature-flags.md): every gate that hides or shows UI
- [Best practices](90-reference/apply-studio-development-best-practices.md): consolidated patterns and anti-patterns

## LLM-driven install + authoring (107 skills)

The 107 skills are plain markdown files in [`prompts/`](prompts/). Install them into your IDE with one command — it asks which of Claude Code, Codex CLI, Gemini CLI, Cursor, Windsurf, Cline, or Continue to wire up, ticking the ones it finds:

```bash
curl -fsSL https://studio-documentation.contentstackapps.com/install.sh | sh
```

Flags skip the prompt: `--ide=<claude,cursor,…>` names editors, `--all` takes every one, `--dir=<path>` adds a custom destination. The skills land once in `.studio/skills/` with each editor symlinked at that copy, so re-running updates all of them together. For any other LLM chat, open a prompt file on the docs site and paste it directly.

**Setup + integration skills**:
- `install-studio` — install + init the three SDKs (Delivery + Live Preview + Studio)

**Authoring + advanced skills**:
- `studio-tour` — intent-driven concierge that walks new users end-to-end through Studio: discovers their goal, maps their current state, surfaces the right specialist skill, and frames the full setup → register → build section → build template → ship path
- `build-connected-template` — author a Connected (CT-bound) template end-to-end. **This is the default flavor; most pages should be Connected, including one-off pages backed by a single-entry CT.**
- `expose-section-props` — surface section component props for per-instance override
- `use-section-slot` — carve a Section Slot inside an existing section
- `configure-slot-defaults` — set a Section Slot's Default section (renders while a placement leaves the slot empty) and Allowed sections whitelist (gates which sections may be dropped)
- `setup-template-preview-routes` — wire `/blog/:slug`-style routes mounting `<StudioComponent />`
- `wire-component-default-data` — add standalone default data so a component renders in the palette preview
- `configure-csr-vs-ssr` — pick + wire the right render path (CSR hook vs `csStudio.fetchCompositionData`)
- `register-breakpoints` — set up responsive design with `registerBreakpoints`
- `register-json-rte` — register a JSON RTE renderer with `registerJSONRTE`
- `deploy-studio-site` — deploy a Studio-built site (Vercel / Netlify / etc.)
- `build-section` — author a new Section composition by linking it to a Global Field schema and dropping registered components
- `use-repeater` — drop a Repeater on the canvas and bind it to a multi-valued field for one-shape-N-renders
- `use-condition-block` — wrap component bindings inside a Repeater with a Condition Block (required for Modular Block lists AND any Reference field including single-CT)
- `wire-external-data` — bring external data (live pricing, URL params, A/B variants, feature flags) into a composition via the data prop on <StudioComponent />, works in both CSR and SSR
- `understand-bring-your-own-data` — pick between the three render-time surfaces for data you already hold: the data prop, StudioComposition's context, and slot data
- `render-with-own-data` — render a composition (page or standalone section) against a context object you supply, via <StudioComposition /> + the spec-only sdk.fetchComposition; CSR + SSR, including one mount per array element
- `wire-slot-data` — wrap a slot prop in <Slot data={...}> so components an author drops into it can bind the owner's data through Component Default Data (nearest slot wins)

Sources for all 107 live at [skills/src/](skills/) (canonical). Paste-into-any-LLM copies live at [prompts/](prompts/).

## Two SDK components — NOT interchangeable

- `<StudioCanvas />` → the **canvas route** only (Project Canvas URL points here; hosts Section previewing). Client-only (`"use client"`).
- `<StudioComponent />` → **template preview routes** (real pages where templates render to visitors). Takes `specOptions` as a prop.
- A typical app ships BOTH.

## Common confusions to avoid

- "Custom Preview URL" is stack-level (Stack → Settings → Visual Experience → Preview URL), NOT per-content-type.
- "Visual Editor" / "Live Preview" enable is stack-level (Stack → Settings → Visual Experience → General), NOT per-content-type.
- UI says "Languages"; API and SDKs say "locales". Same thing.
- "Preview Token" is a paired credential on each Delivery Token record, not a separate token type.
- "Canvas URL" is a project-level path used to preview Sections only. Templates use their own URL patterns at real site routes.
- Prop schemas use `defaultValue:`, NOT `default:`. Prop types are exactly: `string`, `boolean`, `number`, `choice`, `href`, `imageurl`, `datestring`, `array`, `object`, `slot`, `json_rte`, `any` — no `text`, `link`, `color`, `image`.
- `useCompositionData` returns `{ specOptions, isLoading, error, refetchSpec, refetchData }`. Server-side path uses `csStudio.fetchCompositionData(queryOptions, options)` instead.

## Contributing to the docs

Contributor conventions and the anti-hallucination rule (every UI claim cites verified ground truth) are documented in AGENTS.md and _research/ground-truth.md inside the source repo — both are intentionally not shipped to the public docs site.