Website Builder: Preview URL Modifier

TL;DR

PreviewUrlModifier is a DI extension point that lets project developers inject custom query parameters into all Website Builder live preview URLs. Register one implementation; it receives the full URL object and can mutate it however it needs — including async operations like fetching a signed token from a remote API.

Implement the Modifier

Import from webiny/admin/website-builder. The single required method is modify(url: URL): Promise<void> — mutate url.searchParams in place, mark the method async when you need to fetch remote values.

import { PreviewUrlModifier } from "webiny/admin/website-builder";

class MyPreviewUrlModifier implements PreviewUrlModifier.Interface {
  async modify(url: URL) {
    url.searchParams.set("my-param", "my-value");
  }
}

export default PreviewUrlModifier.createImplementation({
  implementation: MyPreviewUrlModifier,
  dependencies: []
});

Async example — fetching a signed token:

class SignedTokenModifier implements PreviewUrlModifier.Interface {
  async modify(url: URL) {
    const token = await fetch("/api/preview-token").then(r => r.text());
    url.searchParams.set("token", token);
  }
}

export default PreviewUrlModifier.createImplementation({
  implementation: SignedTokenModifier,
  dependencies: []
});

Register the Feature

// extensions/previewUrlModifier/index.tsx
import React from "react";
import { createFeature, RegisterFeature } from "webiny/admin";
import MyPreviewUrlModifier from "./MyPreviewUrlModifier.js";

const PreviewUrlModifierFeature = createFeature({
  name: "MyApp/PreviewUrlModifier",
  register(container) {
    container.register(MyPreviewUrlModifier);
  }
});

export default () => <RegisterFeature feature={PreviewUrlModifierFeature} />;

// webiny.config.tsx
<Admin.Extension src={"@/extensions/previewUrlModifier/index.tsx"} />

Where It Applies

Surface	Description
Editor iframe	The live-editing iframe in the page editor
Address bar link	The "copy preview link" button in the editor toolbar
Pages list	Preview icon links in the pages list table

Constraints

One modifier per project. Only the first registered implementation is used.
Mutate in place. Return value is ignored; mutate the URL object directly.
No wb.* collisions. Params prefixed wb. are reserved for internal use.

Related Skills

wb-custom-page-types -- registering custom page types via PageType abstraction
wb-page-settings -- extending page settings groups and fields

wb-preview-url-modifier