Headless Preview Configuration

Status: IMPLEMENTED

See docs/superpowers/specs/2026-03-16-preview-mode-scheduled-publishing-design.md for the canonical design. Approach: Kjac.HeadlessPreview NuGet package + Next.js Draft Mode (new tab, not iframe).

Original Research (below) — kept for reference

Umbraco 17 does not have a native “Save and Preview” → external frontend URL feature. The built-in preview renders using Umbraco’s own templating engine, which is not applicable in a headless setup.

Recommended Approach

1. Content Delivery API — Draft Content Access

Umbraco’s Content Delivery API supports fetching unpublished/draft content via two request headers:

Header	Value	Purpose
`Preview`	`true`	Enables draft content in API responses
`Api-Key`	Configured API key	Authorizes access to unpublished content

Configuration (appsettings.json):

{
  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "PublicAccess": true,
        "ApiKey": "your-preview-api-key-here"
      }
    }
  }
}

2. Next.js Draft Mode

Next.js App Router has built-in Draft Mode support.

Implementation plan:

Create API route apps/web/src/app/api/draft/route.ts:
- Accepts secret, path, and siteKey query params
- Validates secret against PREVIEW_SECRET env var
- Calls draftMode().enable()
- Redirects to the requested path
Modify cms-client fetch calls to detect draft mode and add Preview: true + Api-Key headers
Create API route apps/web/src/app/api/draft/disable/route.ts to exit draft mode

3. Umbraco Backoffice Preview Button

Two options to wire up the backoffice “Preview” button:

Option A: Kjac.HeadlessPreview Package

Community package (GitHub) that replaces the preview button behavior. Install via:

dotnet add package Kjac.HeadlessPreview

Note: Compatibility with Umbraco 17 needs verification. Works with Umbraco 15.

Option B: Custom Preview Controller (Recommended)

Create a custom controller in apps/cms/Savoy.Cms/Controllers/PreviewController.cs that:

Receives the content ID from the backoffice
Resolves the content’s URL path and siteKey
Redirects to http://localhost:3000/api/draft?secret={SECRET}&path={PATH}&siteKey={SITE_KEY}

This is more maintainable than a third-party package dependency.

Environment Variables Needed

Variable	Where	Purpose
`UMBRACO_DELIVERY_API_KEY`	CMS + Next.js	API key for preview requests
`PREVIEW_SECRET`	CMS + Next.js	Shared secret for draft mode activation