register-component

When to use

Read a React component, infer a prop schema, and write a registerComponent call so Studio's palette uses the customer's component instead of built-in defaults. Lazy by default.

Use when the user wants Studio's palette to surface their components: "make my Hero available in Studio", "Studio shows defaults instead of mine", "register components in src/components". The BYOC moment. Do NOT use to register design tokens (use import-design-tokens). Do NOT invent prop schemas. Only register props visible in source.

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.

Reuse preflight: mandatory when the project already has compositions. Before naming a single new atomic, component or Section, run match-existing-pattern § Step 1b: it groups existing Sections by the schema they bind and ranks the component palette by real usage. Decomposition is where reuse has to bite. Once this step names Heading instead of the project's alpha-atom-heading, the duplicate survives into the plan and into the build. Mark every row reuse, extend, or new, and never new without having looked.

Register a component with Studio

Atomic check before you register anything. Registration is where a monolith becomes permanent. If the component renders more than one heading / image / body / list, stop and run decompose-jsx-to-atomics first. Register its atomics and containers, not the whole thing. Registering a page-level component is how a project ends up with one Section, nothing reusable, and a coarse prop that renders blank. Exception: it is genuinely interactive (form, carousel, modal) and cannot be expressed with built-ins, then register it whole and expose an action prop so authors can still wire behavior.

And check reuse first: header, footer, nav and menus are shared across every page. Register the atomics once and bind their lists through a Repeater, rather than registering a per-page variant.

Before you start: walk Q2, Q3, Q4 of the framework

The four questions are defined once in design-component-library § The four-question decision framework. This skill runs the last three. Q1 (classify: atom, layout, or compound?) is answered before you land here: if the input is a compound, decompose-jsx-to-atomics or decompose-design decomposes it into atoms + layouts before registration. If it is already a valid atom or layout, proceed. What registration adds:

Q2 — if an existing primitive covers the shape, reuse it; don't re-register.
Q3 — a prop that fails either half is refused here. Let a DS token decide instead.
Q4 — a prop that fails either half stays static per-Section.

If any answer is ambiguous, halt and ask the user to disambiguate. Never silently register a prop that fails Q3 or expose a prop that fails Q4.

Before you start: pick the layer

Every component you register is one of two shapes. Decide which before writing the registration:

Layer 1: Atomic (renders one CMS field). All scalar props. <Heading>, <Text>, <Image>, <Button>. This skill's default path.
Layer 2: Container / Skeleton / Layout (holds other components). Has at least one slot-typed prop as a drop zone. <Card> with a body slot, <Split> with left+right slots. Same skill. § "Exposing extensible regions with slot props" covers it.

If the thing you want to register is neither: a pure layout primitive (Grid, Stack, Container, Box), a whole page-shaped composition, or a component with an array-of-objects prop. Stop. Read From designs to Sections: the three-layer mental model first. It's a 10-minute page that saves hours of "why doesn't my Grid work in Studio."

Context

Studio composes pages from React components. By default it uses its own built-ins (Hero, Card, Button) so authors can play immediately, but for production, every component should come from the customer's library. Registering tells Studio's palette "use THIS component for type 'site-hero'" so authors drop branded components, not defaults.

The registration is a registerComponent call that names the component, gives it a unique type, and declares the prop schema Studio's right-panel will offer for binding. Prop types are strict and finite, exactly: string, boolean, number, choice, href, imageurl, datestring, array, object, slot, json_rte, any. There is no text, link, color, or image, common false-friends from other systems.

Reference: docs/15-build/10-components/20-register-a-component.md, docs/15-build/10-components/25-component-schema-props-types-and-defaults.md.

Task

Locate the registration entry point. Look for src/register-components.tsx, src/register-studio.ts, or src/lib/contentstack.ts (whichever file imports registerComponent from @contentstack/studio-react). If none exists, create src/register-components.tsx and ensure it's imported once at app startup (before any <StudioCanvas /> or <StudioComponent /> mounts).
Read the component at componentPath. Extract the prop names and types. Source of truth ranked by reliability:
- Explicit TypeScript interface (interface HeroProps { … }), most reliable
- propTypes block, second-best
- Destructured args + JSDoc comments, fallback only

Map each prop to a Studio prop type. Use the exact strings below (13 in total). Anything else is rejected:

Source shape	Studio prop type
`string` / `string \| undefined`	`string`
`number`	`number`
`boolean`	`boolean`
`string` constrained to known values (union literal, enum)	`choice` (set `options:` to the literal values. `defaultValue` is the bare value for single-select (`"centered"`) and an array only when `multiSelect: true`)
URL string used as `href`	`href`
URL string used as image `src`	`imageurl`
ISO date string	`datestring`
array	`array`, binds to a multi-value field (Reference multi, Group multi, Modular Block, scalar multi). Reference sources need `data_sources.resolvedReferences`. Groups / Modular Blocks / scalar multi-values live on the entry and need no resolution. See § Array & object props: binding rules
object	`object`, binds when the shape matches an entry Group / Global Field. See § Array & object props: binding rules
React `children` / placeholder for extensible region	`slot`, fillable at template time via `use-section-slot` § component-slot-prop placement. The prop turns that region of the component into an author-controlled drop target. No `defaultValue` (slots start empty).
rich text (JSON RTE field, HTML payload)	`json_rte`, not `string`. RTE renders markup, and `string` would show it as literal `<p>` text.
unknown / can't infer, and the value is a primitive	`any`, never for object- or array-shaped data. See the flatten trap below
A callback an author should be able to point at your app's logic (`onClick`, `onSelect`, `onSubmit`)	`action`: the author picks a registered studio function. Your component just calls the prop. Needs `registerStudioFunctions`. See `wire-studio-state`. Omit this and interactivity stays hardcoded, so the component is a black box authors can't wire

The `any` flatten trap: why structured data renders blank

any is not a harmless catch-all. Verified in studio-registry/src/data-binder/retrieve-data.ts, the binder runs a recursive single-key unwrap on every prop type except object and array:

// Unwrap single-key objects (common in Contentstack Modular Blocks)
// We only do this if we are not explicitly expecting an object or array.
if (type !== "object" && type !== "array" && !handledRepeaterContext) {
  resolvedData = getFlattenedData(resolvedData);

and getFlattenedData descends as long as the object has exactly one key, ignoring $ and _metadata:

const keys = Object.keys(data).filter((k) => k !== "$" && k !== "_metadata");
if (keys.length === 1) return getFlattenedData(data[keys[0]]);   // recurses

So a single-field block bound to an any prop is silently replaced by its inner value. A block like image_grid → { image: [...] } or tabs → { tabs: [...] } has one real key, so the object you expected never arrives. The component receives the bare inner array. Read it as an object and every lookup is undefined. The array's indices surface as {0,1,2,3}. Blank render, no error, nothing in the console. The _metadata exclusion makes it worse: a block carrying one field plus _metadata still counts as single-key and still unwraps.

The fix is the prop type, not the data. object and array are the only two types that skip the unwrap:

The bound field is	Use	Why
A Group / Global Field / whole block object	`object`	Skips the unwrap. The shape arrives intact
A list: Modular Blocks, multi-Reference, multi-Group, scalar list	`array`	Skips the unwrap. Render with `.map()`
A genuine primitive of unknown type	`any`	Flattening a primitive is a no-op, so it's safe here only

Match the type to the real shape. "The shape varies per block" is not a reason to reach for any. It's a reason to use object.

This is a resolver-level behavior (retrievePropValue), so it bites UI / picker-authored bindings exactly as it bites API-authored ones, not an API-only footgun. It is also not specific to Modular Blocks: any single-key object collapses: a Group with one sub-field, a single-item wrapper, a block carrying one field plus _metadata. Rule of thumb: whenever the value you want is an object or a list, type the prop object / array. any is safe only for a genuine primitive.

These 12 strings govern YOUR registered components only. Studio's built-in nodes (header, plain-text, rich-text, image, …) carry their own prop-type vocabulary, e.g. the built-in Header's text prop is typed plaintext, which is not in the list above and is not valid in a registerComponent schema. Reading an existing composition and copying a built-in's prop type into your registration is a silent rejection. The two vocabularies overlap in places and diverge in others. Never transplant between them. Built-in node types are cataloged in author-composition-via-api § Built-in node type values.

Set defaultValue for every prop where the component has a default value in its source. The default appears as the palette tile preview. Without it, the tile renders blank and authors don't know what the component looks like. Use defaultValue: exactly, NOT default: (the latter is silently ignored).
Ship a thumbnailUrl: every registration, no exceptions. (This and the studioAttributes contract below are two of the six in complete-the-build. Both ship in the same commit as the registration, never as a follow-up.) thumbnailUrl defaults to "" in the registry (studio-registry, registry-options-processor), and Studio then renders a text placeholder instead of a preview. A palette of twenty text placeholders is unusable for the marketers this whole exercise exists to serve, and nothing errors, so it ships unnoticed.

Rules that matter (full guidance + the thumb() helper and tier glyph library: palette-conventions):
- Inline SVG data URI, built with encodeURIComponent. Never a CDN/asset URL. The palette renders inside Studio's iframe, where external requests hit CORS or fail silently, leaving you back at a blank tile.
- Brand tokens for colors, not invented hex.
- Preview the shape, not the pixels: the thumbnail says what kind of thing this is (atomic / slot-shell / pattern).
```
registerComponent({
  type: "site-hero",
  displayName: "Hero",
  component: () => import("./components/Hero"),
  sections: ["Acme · Patterns"],
  thumbnailUrl: thumb(HeroGlyph, "Hero Block"),   // data:image/svg+xml,...
  props: { /* … */ },
});
```
One argument, not two. registerComponent(Hero, { name, … }) — component first, config second — throws Component type is required. Verified against the published @contentstack/studio-registry@1.9.0: registerComponent is typed as one element of the array registerComponents takes, so a component passed first is read as the config and type comes back undefined. Pass one config object; type and component are the only required fields. registerComponents([{ … }], options?) takes an array of the same shape.

Retrofitting an existing registration file? Every registerComponent call without thumbnailUrl is a blank tile today. Sweep them all: grep -c "registerComponent" <file> vs grep -c "thumbnailUrl" <file>. The counts must match.

5b. Next.js App Router: registration must run in the CLIENT realm. A registered component that is (or renders) a "use client" component cannot be registered from a Server Component module graph. On the server the SDK sees a client reference, and Next throws at render time ("Attempted to call the default export of <module> from the server but it's on the client") or the palette silently comes up empty because the registry that got populated was the server-side one.

The rule: registerComponents() runs from the same client boundary that runs studioSdk.init. install-studio already creates one for init (app/studio-init.tsx, "use client", side-effect import of @/lib/contentstack). Put the registration import there too, so both land in the client bundle in the right order:

// app/studio-init.tsx
"use client";
import "@/lib/contentstack";        // studioSdk.init
import "@/lib/studio-components";   // registerComponent calls — SAME client boundary
export function StudioInit() { return null; }

Do not import the registration module from app/layout.tsx, a page.tsx Server Component, or any non-"use client" module. Pages Router / Vite / Remix don't have this split. A module-scope import in _app.tsx or main.tsx is fine. Related: install-studio § App Router init boundary, and troubleshoot-ssr-rendering for the registry-singleton symptoms.

Write the registration: prefer LAZY by default. Append (or update) the registration file. The recommended shape is lazy: the component is downloaded only when it first renders, keeping the initial bundle small and code-splitting each registration automatically. The SDK wraps the dynamic import() with React.lazy + Suspense for you.

import { registerComponent } from "@contentstack/studio-react";

registerComponent({
  type: "site-hero",                                    // componentType — unique UID
  displayName: "Hero",                                  // componentName — palette label
  component: () =>                                      // ← LAZY: arity-0 thunk that returns a dynamic import
    import("./components/Hero").then(m => ({ default: m.Hero })),
  props: {
    headline:    { type: "string",   displayName: "Headline",    defaultValue: "Welcome" },
    description: { type: "string",   displayName: "Description", defaultValue: "Lorem ipsum" },
    imageUrl:    { type: "imageurl", displayName: "Image",       defaultValue: "https://…" },
    ctaHref:     { type: "href",     displayName: "CTA Link",    defaultValue: "/get-started" },
    layout:      { type: "choice",   displayName: "Layout",      defaultValue: ["centered"], options: ["centered", "split"] },
  },
});

If the component is the default export: component: () => import("./components/Hero") is enough. An explicit form registerLazyComponent(config, loader) exists with identical runtime behavior.

5a. Exposing extensible regions with slot props. To let template authors drop content into a region of the component (a card body, a sidebar, a CTA area), declare a slot-typed prop. The component renders the prop wherever the extensible region should appear. Studio surfaces it as a drop target for any component or Section.

import { registerComponent } from "@contentstack/studio-react";

registerComponent({
  type: "site-card",
  displayName: "Card",
  component: () => import("./components/Card"),
  props: {
    title: { type: "string", displayName: "Title", defaultValue: "Card title" },
    body:  { type: "slot",   displayName: "Body" },   // ← extensible region, no defaultValue
  },
});

The React component receives the slot as a prop (or via children, depending on what its TypeScript interface declares) and renders it inside its tree:

function Card({ title, body }: { title: string; body: React.ReactNode }) {
  return <div className="card"><h3>{title}</h3>{body}</div>;
}

At template-authoring time, the slot region shows as a dashed drop target. Authors drop a component or Section into it (see use-section-slot § component-slot-prop placement for the canonical filling pattern). Slots take ANY component or Section. There is no type constraint. Slot fills are stored per-template, so the same Card can carry different filled content on different templates.

For a richer pattern (slot count driven by another prop, slot template factories), see docs/15-build/10-components/25-component-schema-props-types-and-defaults.md § slot.

5b. The two valid component: shapes, decided by arity:

Shape	`component:` value	When
Lazy (default)	arity-0 function returning a `Promise` (dynamic `import()`)	Every BYOC registration unless tiny+hot.
Eager	function with ≥1 parameter (ordinary React component)	Tiny components on hot paths.

component: () => import("./components/Hero")          // ✅ LAZY
component: Hero                                       // ✅ EAGER — function Hero(props) {…}
component: (props) => createElement(Hero, props)      // ✅ EAGER — wrap arity-0

Arity-0 trap. A parameter-less function that does NOT return a Promise (e.g. function Header() {…}) is treated as a lazy loader, called outside render, and throws React #321 "Invalid hook call". Rule: return a Promise (lazy), OR give it a props parameter (eager).

Confirm Studio palette shows the new tile. Open the canvas, switch the palette accordion to Registered Components, find Hero. The tile must show the thumbnail image. A text placeholder means thumbnailUrl is missing or the data URI is malformed. A broken-image icon means you used an external URL and the iframe blocked it. The tile preview itself renders from the defaultValues. If that area is blank, a prop is missing a default or the prop type was wrong.

Inputs needed from the user

componentPath: file path to read.
componentName: display label.
componentType: unique kebab-case UID (reject duplicates. Check the registration file before writing).

Do NOT invent component paths. If the user just says "register my Hero" without a path, ask which file.

The registration contracts: read the one you need

Registration has four contracts a component must honour. They are reference material, split out so a task loads only what it touches.

Read this	For
`register-component-prop-contracts`	Array and object binding rules, tolerant image and link signatures, `{{entry.*}}` resolution
`register-component-render-contracts`	Layout-agnostic rule, null-safe rendering
`register-component-cslp`	`$` CSLP props and the `studioAttributes` contract. Both or neither.
`register-component-pitfalls`	What fails silently, and why. Read before reporting done.

Acceptance

This skill succeeds only when ALL of the following are true.

After registering: plan your Section shape

Compound component that iterates internally (say <BlogArticle> doing .map(sections), <CardList> doing .map(related_posts)): build top-down. Author the wrapping Simple Section first, one Section that wraps the whole compound. Studio renders your existing page inside its canvas in ~5 minutes with no code changes. Then decompose one Section per iteration level as you need each to become author-editable.
Atomic component that renders one shape (<Card> bound to card_ref, <Hero> bound to hero_group): author its Simple Section directly. Compose it later inside a List Section when a parent iteration needs to drop it as a slot's default content.

Both directions produce the same Section chain in the end. Top-down is faster for existing compound-heavy apps. Bottom-up has a cleaner mental model for greenfield.

Use build-section (or build-repeating-section for List Sections) to author each Section. The skill walks the Studio-UI flow. Full worked example with a 4-level nested schema: From components to Studio compositions.

When to use​

Register a component with Studio

Before you start: walk Q2, Q3, Q4 of the framework​

Before you start: pick the layer​

Context​

Task​

The any flatten trap: why structured data renders blank​

Inputs needed from the user​

The registration contracts: read the one you need​

Acceptance​

After registering: plan your Section shape​

See also​