---
name: macro-sdk
description: >-
  Integrate @macrocontent/sdk and @macrocontent/overlay — macro.config.js,
  Vite plugin, credentials, data-macro-key marking, primitives, and editor login.
  Use when adding macrocontent to a site or debugging SDK boot / marking.
---

# macrocontent SDK integration

## Packages

```bash
pnpm add @macrocontent/sdk @macrocontent/overlay
```

## Docs (read these)

- Quickstart: https://docs.macrocontent.dev/developers/quickstart/
- Credentials: https://docs.macrocontent.dev/developers/credentials/
- Config: https://docs.macrocontent.dev/developers/config/
- Vite: https://docs.macrocontent.dev/developers/vite/
- Marking: https://docs.macrocontent.dev/developers/marking/
- Primitives: https://docs.macrocontent.dev/developers/primitives/
- Forms: https://docs.macrocontent.dev/developers/forms/

## Credentials

- `websiteId` + frontend key (`pk_…` production, `dk_…` local/staging) belong in `macro.config.js`.
- Never put management tokens (`mt_…`) or secrets in frontend config.
- Details: https://docs.macrocontent.dev/developers/keys/

## Marking

- Every editable node needs `data-macro-key` (stable, no locale suffix).
- Type via tag inference or `data-macro-type` (e.g. `richtext` must be explicit).
- Prefer primitives for single fields (heading, image, link).

## Editor

- Overlay opens with **⌘⇧M** / **Ctrl+Shift+M** after login (no separate `/login` page on the site).
- Changes autosave to draft; publish promotes draft → live.

## Checklist

1. Install packages + Vite plugin (or layout loader).
2. Configure `macro.config.js` with real website credentials.
3. Mark first key; open editor; verify draft save.
4. Only then add custom components if needed (see `macro-components` skill).