Kraftvaerk.Umbraco.Headless.Preview 1.2.0

Kraftvaerk.Umbraco.Headless.Preview

Preview support for headless Umbraco projects.
This package replaces Umbraco's built-in preview (/umbraco/preview) with a secure iframe that points to your configured frontend application.

How it works

1. When an editor clicks Preview in Umbraco, this package renders an iframe instead of the standard MVC page.
   The iframe URL is built from configuration:

   _previewPath = configuration.GetValue<string>("HeadlessPreview:Url") ?? string.Empty;
   var url = $"{_previewPath}?id={contentKey}&secret={secret}&uid={backofficeUserId}&rand={Guid.NewGuid()}";
   

   • id = Umbraco content key
   • secret = short-lived handshake token
   • uid = current backoffice user id
   • rand = random Guid to defeat caching

2. Your frontend app should read the query parameters and call back to Umbraco:

   GET /api/custompreviewapi/check?key={secret}&id={uid}
   

3. If the secret is valid, the API responds 200 OK with a new long-lived preview Guid.
   Your frontend app should store this Guid (e.g. in a cookie).

4. When requesting content from the Delivery API in preview mode, your frontend app should send:

   GET /umbraco/delivery/api/v1/content/item/{id}
   Api-Key: <your-delivery-key>
   Preview: true
   X-UMB-PREVIEW: <guid-from-check>
   

5. On the Umbraco side, the package extends IRequestMemberAccessService to allow access when the provided Guid matches what is stored in memory.

Configuration

Add to appsettings.json:

{
  "HeadlessPreview": {
      "Url": "http://localhost:5173/preview"
  }
}

• Url: the entrypoint of your frontend preview app.

Example frontend (Node + Vite)

A minimal runnable example frontend is included in example-frontend.

cd example-frontend
npm install
npm run dev

Defaults:

• Frontend URL: http://localhost:5173/preview
• Umbraco target: http://localhost:6783 (configurable in example-frontend/.env.example)
• Delivery API key: local-preview-api-key

Features

• Overrides /umbraco/preview with an iframe preview experience
• Secure handshake between Umbraco and your frontend app
• One-time secret + time-limited preview token
• Integrates seamlessly with the Umbraco Delivery API

Security

• Secrets are short-lived and tied to the initiating backoffice user.
• Preview tokens automatically expire after a limited TTL.
• All access is validated server-side before unpublished content is returned.