Overlay & login

Packages

pnpm add @macrocontent/sdk @macrocontent/overlay

With the Vite plugin (or loader), Macro dynamically imports DefaultMacroOverlay when overlay is enabled. If the overlay package fails to load, the SDK continues in read/hydrate mode and logs a warning.

Config

export const macroConfig = {
  apiBaseUrl: 'https://api.macrocontent.dev',
  websiteId: 'your-website-uuid',
  publicKey: 'pk_...',
  editorLogin: {
    enabled: true,
    shortcut: 'Mod+Shift+M',
    triggers: true,
  },
  overlay: {
    enabled: true,
    theme: 'dark',
    position: 'bottom-right',
    mode: 'full',
    showCloseButton: true,
  },
  openOverlayOnSession: true,
  enableInlineEditing: true,
}

Login triggers

Besides the keyboard shortcut, any element with data-macro-editor-login-trigger opens the modal when editorLogin.triggers is true (default).

<button type="button" data-macro-editor-login-trigger>
  Edit with macrocontent
</button>

Session flow

1. 0

   Visitor / anonymous

   SDK hydrates live content with the frontend key. Overlay editing stays closed.

2. 0

   Editor signs in

   Modal authenticates a website editor (site_users) for this websiteId. Session cookies / tokens are website-scoped.

3. 0

   Overlay activates

   Inline editing, sidebar, drafts, and SEO tab become available. Autosave writes to the active draft. See the Editors handbook.

Programmatic init

For custom boots (without the loader), the contract looks like:

import { initMacroSdk } from '@macrocontent/sdk'

await initMacroSdk({
  websiteId: 'website-uuid',
  apiBaseUrl: 'https://api.macrocontent.dev',
  publicKey: 'pk_...',
  editorLogin: { enabled: true, shortcut: 'Mod+Shift+M' },
  autoSaveDebounceMs: 800,
  overlay: true,
})

Theme & chrome

• theme: 'dark' | 'light' selects overlay theme tokens.
• Position corners: bottom/top × left/right.
• Editor chrome selectors (data-macro-editor-*) are excluded from “click outside = deselect content” logic.