Developers

Vite plugin

Inject the macrocontent loader on every HTML entry and optionally prerender live content after vite build.

One plugin, all pages

After you add macro() once, new pages only need data-macro-key — no manual script tags and no main.js bootstrap.

Install and wire

bash

pnpm add @macrocontent/sdk @macrocontent/overlay

vite.config.ts

import { defineConfig } from 'vite'
import { macro } from '@macrocontent/sdk/vite'

export default defineConfig({
  plugins: [macro({ config: '/macro.config.js' })],
})

Plugin options

Name	Type	Required	Description
`config`	`string`	optional	Public URL path to macro.config.js. Default '/macro.config.js'.
`inject`	`boolean`	optional	Inject loader on every HTML entry. Default true.
`prerender`	`object`	optional	Build-time live content + SEO injection options.

What transformIndexHtml does

Runs on every HTML entry with order: 'pre'.
Skips injection if the HTML already contains data-macro-loader (idempotent).
Injects a module script that imports @macrocontent/sdk/loader with data-config pointing at your config URL path.
Defines __MACRO_CONFIG_PATH__ so the loader knows the default config path.

Prerender after build

When prerender.enabled is true, the plugin runs after closeBundle on vite build: reads MACRO_SECRET_KEY (or custom env), loads macro.config.js, and injects live body + SEO into outDir.

vite.config.ts

import { defineConfig } from 'vite'
import { macro } from '@macrocontent/sdk/vite'

export default defineConfig({
  plugins: [
    macro({
      config: '/macro.config.js',
      prerender: {
        enabled: true,
        locale: 'en',
        apiKeyEnv: 'MACRO_SECRET_KEY',
      },
    }),
  ],
})

Name	Type	Required	Description
`enabled`	`boolean`	optional	Run prerender after vite build when true.
`locale`	`string`	optional	Content locale; falls back to macro.config defaultLocale.
`apiKeyEnv`	`string`	optional	Env var name for server key. Default 'MACRO_SECRET_KEY'.
`configFile`	`string`	optional	Absolute or project-relative path to macro.config.js.

Secret stays in env

Prerender throws if the API key env var is missing. Never put sk_ / mt_ in macro.config.js. Full guide: Prerender.

Non-Vite sites

Add the loader once in a shared layout:

layout.html

<script
  type="module"
  src="/node_modules/@macrocontent/sdk/dist/loader.js"
  data-config="/macro.config.js"
  data-macro-loader
></script>

Or call macro-prerender CLI after your own build — see Prerender.

Disable injection

Set inject: false when you boot Macro yourself (custom initMacroSdk / autoStartMacro path) but still want the plugin’s prerender hook.