mdcms-studio-embed

MDCMS Studio Embed

Mount the MDCMS Studio UI inside the user's own host app so editors work alongside product code. The canonical reference is apps/studio-example in the MDCMS repo — use it as the copy-from template for route structure, config preparation, and client bootstrap.

When to use this skill

The user wants a Studio UI under their own domain (e.g. app.example.com/admin/...) instead of running Studio standalone. If they only need the API and use Studio at the server's own /admin/studio route, skip.

Prerequisites

• A reachable MDCMS server and a working mdcms.config.ts (run mdcms-brownfield-init or mdcms-greenfield-init first).
• A React app, ideally Next.js App Router. Other frameworks work but the reference implementation is Next.
• Ability to set server-side env vars on the MDCMS backend (for MDCMS_STUDIO_ALLOWED_ORIGINS).

Steps

1. Install the Studio package in the host app

npm install @mdcms/studio
# or: bun add @mdcms/studio

2. Add a catch-all route

Studio is a single page app embedded at a catch-all route. The reference uses /admin/[[...path]] so every Studio route is served from one Next page. Copy the pattern from apps/studio-example/app/admin/[[...path]] in the MDCMS repo:

app/
  admin/
    [[...path]]/
      page.tsx        # server component that prepares Studio config
      layout.tsx      # minimal layout (Studio brings its own chrome)
    admin-studio-client.tsx   # client wrapper that mounts <Studio />
    studio-config.ts          # prepareStudioConfig + client-serialized subset

The server component calls prepareStudioConfig from @mdcms/studio/runtime against the full mdcms.config.ts, extracts a client-safe subset (component metadata, schema hash, route metadata), and passes it to the client wrapper.

3. Wire the prepared config to <Studio />

The client wrapper uses the <Studio /> component and the prepared config:

"use client";
import { Studio } from "@mdcms/studio";
import type { MdcmsConfig } from "@mdcms/studio";

export function AdminStudioClient({ config }: { config: MdcmsConfig }) {
  return <Studio config={config} />;
}