mdcms-mdx-components

MDCMS MDX Components

Register custom React components so they render consistently inside:

1. The author's MDX source files,
2. The Studio preview (editors see them in the visual editor), and
3. The host app's SSR / CSR output (production renders them too).

When to use this skill

The user has MDX content that uses custom components (<Callout>, <CTAButton>, <Chart>, <Video>) and wants them to "just work" end to end. Also use when a component renders fine in one place (e.g., the host app) but not another (e.g., Studio shows the raw tag or empty content).

Not for schema changes (mdcms-schema-refine) or for regular markdown (no registration needed).

Prerequisites

• mdcms.config.ts exists (run mdcms-brownfield-init or mdcms-greenfield-init first).
• Host app already has MDX rendering set up (or is willing to add it — see the target framework's MDX integration).
• Each custom component is a React component in the host app's source tree.

How components flow

The MDCMS contract is: components are declared once, in a shared module, and referenced from both mdcms.config.ts and the host app's MDX runtime. Studio reads the config to know which components exist and how to render them in preview; the host app reads the same registry to render them in production.

The apps/studio-example repo demonstrates the current pattern — treat it as the canonical reference when file paths or export names change.

Steps

1. Create a shared components module

Create a single source of truth for component metadata and implementations:

// lib/mdcms-components.ts
import { Callout } from "@/components/callout";
import { CTAButton } from "@/components/cta-button";

export const mdcmsComponents = [
  {
    name: "Callout",
    component: Callout,
  },
  {
    name: "CTAButton",
    component: CTAButton,
  },
];

Exact shape (keys like name, component, extractedProps) comes from @mdcms/studio's component contract — check apps/studio-example/lib/*-studio-config.ts for the current field set. Do not invent fields; copy from the reference.