Skip to main content

understand-installation

When to use​

Explain what installing Contentstack Studio adds to a project: three SDKs (delivery / live-preview / studio-react), one shared init, two component mounts (StudioCanvas + StudioComponent). Concept on-ramp before install-studio.

Use when a new user asks "what does installing Studio do", "what packages are added", "which SDKs do I need", "what's StudioCanvas vs StudioComponent", or is about to run install-studio without context. Concept only: for the actual install run install-studio. Do NOT use to fix an install (use troubleshoot-canvas or verify-setup). Do NOT use for component registration (use register-component).

Auth preflight: settle the credential before the first API call. Resolve it OAuth-first per authenticate-cma: CS_OAUTH_ACCESS_TOKEN, else the Contentstack MCP's stored session: Read that skill for where it is, even with no MCP connected. Never ask the user for a session authtoken. If nothing resolves, or a refresh fails with 400 invalid_refresh_token, hand them ! CONTENTSTACK_REGION=<code> npx @contentstack/mcp --auth (it needs a TTY and a browser, so it cannot be run for them) and wait. 403 error_code 316 is a valid credential aimed at another org: fix the org or the api_key, do not re-authenticate.

What installing Studio adds to your project

The three SDKs​

Installing Studio adds three packages to your app. They're effectively one install. Each owns a distinct piece:

PackageWhat it doesWhose credentials
@contentstack/delivery-sdkReads published content from Contentstack's CDA.Stack API Key + Delivery Token
@contentstack/live-preview-utilsReal-time edit channel: Studio's iframe pushes edits to your running app within ~1s.Preview Token (paired with the Delivery Token)
@contentstack/studio-reactThe Studio bridge: studioSdk (init), <StudioCanvas /> (canvas mount), <StudioComponent /> (visitor + template-preview mount), plus hooks like useCompositionData.(uses the other two via studioSdk.init({ stackSdk }))

You don't install one without the others: install-studio wires all three.

The two React components, and where each goes​

This is the single most-confused part of the install:

  • <StudioCanvas /> mounts on ONE canvas route (e.g. /canvas). It's the surface Studio's iframe uses to author Sections. Visitors never hit this route. Set the Canvas URL in Project Settings to the path you mount it on. See setup-section-preview.
  • <StudioComponent /> mounts on ONE catch-all route (app/[[...slug]]/page.tsx for Next App Router, <Route path="*"> for React Router). Studio resolves EVERY visitor URL through this one mount via sdk.fetchCompositionData({ url }). No per-template routes. See setup-template-preview-routes.

Two mounts. Total. The install does not add per-template routes.

What gets wired at install time​

After install-studio completes:

  1. Three SDK packages in package.json.
  2. src/lib/contentstack.ts (or framework equivalent): the single bootstrap module. Exports stack, sdk, optionally ContentstackLivePreview. This is where studioSdk.init({ stackSdk, contentTypeUid }) happens.
  3. A side-effect import at the app shell so the bootstrap runs once. Next App Router needs a "use client" StudioInit boundary. Vite / Pages Router / Remix import directly.
  4. .env.local with the five credentials.

The two route mounts are SEPARATE skills: setup-section-preview adds the canvas route. setup-template-preview-routes adds the catch-all visitor route. install-studio deliberately stops before them so each route is an explicit decision.

What install does NOT do​

  • Does NOT register any of your components. That's register-component.
  • Does NOT configure the Studio project (Environment, Canvas URL). That's configure-studio, done in app.contentstack.com.
  • Does NOT enable Live Preview at the stack level. That's enable-visual-experience, done in Stack settings BEFORE the app-side install.

The expected install order​

  1. analyze-project-fit: preflight, picks greenfield vs minimal-add path.
  2. enable-visual-experience: turn on Live Preview at stack level (otherwise app install succeeds silently but nothing flows).
  3. install-studio: adds the three SDKs, writes the bootstrap module.
  4. register-component: register the customer's components so Studio's palette uses them.
  5. setup-section-preview: adds the /canvas route.
  6. setup-template-preview-routes: adds the catch-all visitor route.
  7. configure-studio: set Environment, Canvas URL in the Studio web app.
  8. verify-setup: confirm all four layers green.

This sequence is also walked by studio-tour and byoc-end-to-end orchestrators when you want one skill driving the whole flow. On an existing app, convert-project-to-studio runs steps 1 to 3 and 5 to 8 as a minimal conversion that leaves every current page untouched.

What this skill is NOT​

  • Not the install itself. Run install-studio.
  • Not a troubleshooting guide. Run troubleshoot router if something's broken.
  • Not the conceptual onboarding for new-to-Studio users. That's start-here-zero-knowledge.

Report a problem with this page