mdcms-sdk-integration

MDCMS SDK Integration

Use @mdcms/sdk in the host app to fetch MDCMS content at build time or request time, replacing any filesystem-driven content layer, and supporting the draft/published split.

When to use this skill

The user wants to consume MDCMS content programmatically from a host app — typically to render pages, build a blog index, or hydrate a CMS-driven section. Two sub-paths:

• Brownfield (replace) — the app currently imports markdown from the repo (import about from "../content/about.md", fs.readFile, remark/mdx-bundler). Replace that with SDK calls.
• Greenfield (write new) — the app has no content-fetching code yet. Add it fresh.

Not for editing content (use Studio), not for schema changes (use mdcms-schema-refine), not for admin embedding (use mdcms-studio-embed).

Prerequisites

• A running MDCMS server and content synced against a schema (via mdcms-brownfield-init or mdcms-greenfield-init).
• A React-based host app.
• An API key that the host app can read at runtime. For server-side rendering, this is an env var (MDCMS_API_KEY). Never ship the API key to the browser.

Steps

1. Install the SDK

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

2. Create a client

In a server-only module (for Next: a file without "use client", ideally under lib/):

import { createClient } from "@mdcms/sdk";

export const cms = createClient({
  serverUrl: process.env.MDCMS_SERVER_URL!,
  project: process.env.MDCMS_PROJECT!,
  environment: process.env.MDCMS_ENVIRONMENT!,
  apiKey: process.env.MDCMS_API_KEY!,
});

Keep the import path server-only. If the app leaks it into a client bundle, the API key ships to users.

3. Fetch content

The SDK exposes two read methods: cms.get(type, input) and cms.list(type, input). Both accept locale, optional per-call project/environment overrides, and an optional resolve array for reference expansion.

Fetch a single document by id or slug