payload-live-preview 1.0.0

package/dist/middleware-BwIlf0jW.d.cts

@@ -0,0 +1,168 @@
+/**
+ * Public types for the Astro adapter.
+ *
+ * @module @adapters/astro/types
+ */
+interface LivePreviewAstroOptions {
+    /**
+     * How the integration wires the preview:
+     *
+     *   - `'inline'` (default) — bake the runtime into every page at
+     *     build time. For `output: 'static'` projects.
+     *   - `'middleware'` — auto-register the preview middleware:
+     *     request-time injection into preview requests only, plus
+     *     `frame-ancestors` CSP management. For `output: 'server'`.
+     *     (`shouldInject` is unsupported here — options serialize into
+     *     the build.)
+     */
+    readonly mode?: 'inline' | 'middleware';
+    /**
+     * Trusted Payload admin origin(s). Required in production unless
+     * `document.referrer` reliably exposes the parent origin.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /**
+     * Payload server origin, e.g. `https://cms.example.com`. When set,
+     * incoming updates are re-fetched through the Payload REST API so
+     * relationship/upload fields render populated instead of as bare
+     * IDs. Strongly recommended for Payload 3.x.
+     */
+    readonly serverURL?: string;
+    /** REST API route prefix used with `serverURL`. Defaults to `/api`. */
+    readonly apiRoute?: string;
+    /** Population depth used with `serverURL`. Defaults to `1`. */
+    readonly mergeDepth?: number;
+    /**
+     * Auto-inject the inline preview script. Default `true`. Disable to
+     * embed the script manually via `renderLivePreviewScript()`.
+     */
+    readonly autoInject?: boolean;
+    /**
+     * When the middleware injects the script (integration-based
+     * injection is always build-time and unaffected):
+     *
+     *   - `'preview-only'` (default) — only into responses that look
+     *     like preview requests (`?preview=true` / `?draft=true` query,
+     *     `Sec-Fetch-Dest: iframe`, or a referer from `allowedOrigins`).
+     *     Normal production traffic passes through untouched.
+     *   - `'always'` — into every HTML response.
+     */
+    readonly inject?: 'preview-only' | 'always';
+    /**
+     * Query parameters that mark a request as a preview (values `true`
+     * or `1`). Default: `['preview', 'draft', 'livePreview']`.
+     */
+    readonly previewQueryParams?: readonly string[];
+    /**
+     * Which signals count as a preview request. Default: all three
+     * (`query`, `fetch-dest`, `referer`). Restrict to `['query']` when
+     * an unsolicited iframe load must never trigger preview handling
+     * (e.g. sites that serve `frame-ancestors 'none'` and only allow
+     * preview via the explicit `?preview=true` URL).
+     */
+    readonly previewSignals?: readonly ('query' | 'fetch-dest' | 'referer')[];
+    /**
+     * Restrict auto-inject to requests where this function returns
+     * `true`. Applied on top of the `inject` mode.
+     */
+    readonly shouldInject?: (request: Request) => boolean;
+    /**
+     * Content-Security-Policy management on preview responses:
+     *
+     *   - `'frame-ancestors'` (default) — merge a `frame-ancestors`
+     *     directive allowing the admin origins to embed the page.
+     *     Existing CSP directives are preserved (union merge).
+     *   - `'full'` — additionally manage `script-src` with a
+     *     per-request nonce. Only useful when your whole page is
+     *     nonce-disciplined; see `strictDynamic`.
+     *   - `false` — never touch CSP headers.
+     *
+     * `true` is accepted as a legacy alias for `'frame-ancestors'`.
+     */
+    readonly manageCsp?: boolean | 'frame-ancestors' | 'full';
+    /**
+     * Add `'strict-dynamic'` to the managed `script-src` (only with
+     * `manageCsp: 'full'`). ⚠️ Under CSP 3 this makes browsers ignore
+     * `'self'` and host sources — every script on the page must then
+     * carry the nonce or be loaded by a nonce-carrying script. Astro's
+     * own hydration scripts do NOT carry it, so leave this off unless
+     * you know your page is fully nonce-disciplined. Default `false`.
+     */
+    readonly strictDynamic?: boolean;
+    /**
+     * Extra `frame-ancestors` sources to merge with the auto-detected
+     * ones. Always includes `'self'` and every entry in `allowedOrigins`.
+     */
+    readonly frameAncestorsExtra?: readonly string[];
+    /**
+     * Extra `script-src` sources (e.g., a CDN) appended after the nonce
+     * (only with `manageCsp: 'full'`).
+     */
+    readonly scriptSrcExtra?: readonly string[];
+    /**
+     * Enable verbose debug logging in the injected client. Default: dev mode.
+     */
+    readonly debug?: boolean;
+    /**
+     * Debounce window for incoming updates. Default: 50 ms.
+     */
+    readonly debounceMs?: number;
+    /**
+     * Heartbeat timeout in ms. Default `0` (disabled — the Payload admin
+     * sends no keepalive, so an idle timeout would cause false
+     * disconnects).
+     */
+    readonly heartbeatMs?: number;
+}
+
+/**
+ * Astro middleware for Payload Live Preview.
+ *
+ * Responsibilities (per request):
+ *
+ *   1. Generate a per-response CSP nonce and stash it on
+ *      `Astro.locals.livePreviewNonce` so consumers can reference it.
+ *   2. On **preview requests only** (see `isPreviewRequest`), rewrite
+ *      the HTML response to inject the live-preview `<script>` tag.
+ *      Normal production traffic streams through untouched — no
+ *      buffering, no extra bytes.
+ *   3. On preview requests, merge `frame-ancestors` into the
+ *      `Content-Security-Policy` header so the Payload admin may embed
+ *      the page. Full `script-src` nonce management is opt-in via
+ *      `manageCsp: 'full'`.
+ *
+ * Prerendered pages are skipped entirely: Astro runs middleware at
+ * build time for those, where per-request nonces and response headers
+ * are meaningless.
+ *
+ * @module @adapters/astro/middleware
+ */
+
+type MiddlewareNext = () => Promise<Response>;
+interface MiddlewareContext {
+    readonly request: Request;
+    readonly locals: Record<string, unknown>;
+    /** Present in Astro ≥ 5: `true` while prerendering at build time. */
+    readonly isPrerendered?: boolean;
+}
+type LivePreviewMiddleware = (context: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
+/**
+ * Key on `Astro.locals` carrying the request-scoped nonce. Consumers
+ * can read `Astro.locals.livePreviewNonce` from `.astro` templates to
+ * set the `nonce` attribute on their own scripts.
+ */
+declare const NONCE_LOCALS_KEY = "livePreviewNonce";
+/**
+ * Build the Astro-compatible middleware. Register it in
+ * `src/middleware.ts`:
+ *
+ * ```ts
+ * import { createLivePreviewMiddleware } from 'payload-live-preview/astro';
+ * export const onRequest = createLivePreviewMiddleware({
+ *   allowedOrigins: [import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN],
+ * });
+ * ```
+ */
+declare function createLivePreviewMiddleware(options?: LivePreviewAstroOptions): LivePreviewMiddleware;
+
+export { type LivePreviewAstroOptions as L, NONCE_LOCALS_KEY as N, type LivePreviewMiddleware as a, createLivePreviewMiddleware as c };

package/dist/middleware-BwIlf0jW.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Public types for the Astro adapter.
+ *
+ * @module @adapters/astro/types
+ */
+interface LivePreviewAstroOptions {
+    /**
+     * How the integration wires the preview:
+     *
+     *   - `'inline'` (default) — bake the runtime into every page at
+     *     build time. For `output: 'static'` projects.
+     *   - `'middleware'` — auto-register the preview middleware:
+     *     request-time injection into preview requests only, plus
+     *     `frame-ancestors` CSP management. For `output: 'server'`.
+     *     (`shouldInject` is unsupported here — options serialize into
+     *     the build.)
+     */
+    readonly mode?: 'inline' | 'middleware';
+    /**
+     * Trusted Payload admin origin(s). Required in production unless
+     * `document.referrer` reliably exposes the parent origin.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /**
+     * Payload server origin, e.g. `https://cms.example.com`. When set,
+     * incoming updates are re-fetched through the Payload REST API so
+     * relationship/upload fields render populated instead of as bare
+     * IDs. Strongly recommended for Payload 3.x.
+     */
+    readonly serverURL?: string;
+    /** REST API route prefix used with `serverURL`. Defaults to `/api`. */
+    readonly apiRoute?: string;
+    /** Population depth used with `serverURL`. Defaults to `1`. */
+    readonly mergeDepth?: number;
+    /**
+     * Auto-inject the inline preview script. Default `true`. Disable to
+     * embed the script manually via `renderLivePreviewScript()`.
+     */
+    readonly autoInject?: boolean;
+    /**
+     * When the middleware injects the script (integration-based
+     * injection is always build-time and unaffected):
+     *
+     *   - `'preview-only'` (default) — only into responses that look
+     *     like preview requests (`?preview=true` / `?draft=true` query,
+     *     `Sec-Fetch-Dest: iframe`, or a referer from `allowedOrigins`).
+     *     Normal production traffic passes through untouched.
+     *   - `'always'` — into every HTML response.
+     */
+    readonly inject?: 'preview-only' | 'always';
+    /**
+     * Query parameters that mark a request as a preview (values `true`
+     * or `1`). Default: `['preview', 'draft', 'livePreview']`.
+     */
+    readonly previewQueryParams?: readonly string[];
+    /**
+     * Which signals count as a preview request. Default: all three
+     * (`query`, `fetch-dest`, `referer`). Restrict to `['query']` when
+     * an unsolicited iframe load must never trigger preview handling
+     * (e.g. sites that serve `frame-ancestors 'none'` and only allow
+     * preview via the explicit `?preview=true` URL).
+     */
+    readonly previewSignals?: readonly ('query' | 'fetch-dest' | 'referer')[];
+    /**
+     * Restrict auto-inject to requests where this function returns
+     * `true`. Applied on top of the `inject` mode.
+     */
+    readonly shouldInject?: (request: Request) => boolean;
+    /**
+     * Content-Security-Policy management on preview responses:
+     *
+     *   - `'frame-ancestors'` (default) — merge a `frame-ancestors`
+     *     directive allowing the admin origins to embed the page.
+     *     Existing CSP directives are preserved (union merge).
+     *   - `'full'` — additionally manage `script-src` with a
+     *     per-request nonce. Only useful when your whole page is
+     *     nonce-disciplined; see `strictDynamic`.
+     *   - `false` — never touch CSP headers.
+     *
+     * `true` is accepted as a legacy alias for `'frame-ancestors'`.
+     */
+    readonly manageCsp?: boolean | 'frame-ancestors' | 'full';
+    /**
+     * Add `'strict-dynamic'` to the managed `script-src` (only with
+     * `manageCsp: 'full'`). ⚠️ Under CSP 3 this makes browsers ignore
+     * `'self'` and host sources — every script on the page must then
+     * carry the nonce or be loaded by a nonce-carrying script. Astro's
+     * own hydration scripts do NOT carry it, so leave this off unless
+     * you know your page is fully nonce-disciplined. Default `false`.
+     */
+    readonly strictDynamic?: boolean;
+    /**
+     * Extra `frame-ancestors` sources to merge with the auto-detected
+     * ones. Always includes `'self'` and every entry in `allowedOrigins`.
+     */
+    readonly frameAncestorsExtra?: readonly string[];
+    /**
+     * Extra `script-src` sources (e.g., a CDN) appended after the nonce
+     * (only with `manageCsp: 'full'`).
+     */
+    readonly scriptSrcExtra?: readonly string[];
+    /**
+     * Enable verbose debug logging in the injected client. Default: dev mode.
+     */
+    readonly debug?: boolean;
+    /**
+     * Debounce window for incoming updates. Default: 50 ms.
+     */
+    readonly debounceMs?: number;
+    /**
+     * Heartbeat timeout in ms. Default `0` (disabled — the Payload admin
+     * sends no keepalive, so an idle timeout would cause false
+     * disconnects).
+     */
+    readonly heartbeatMs?: number;
+}
+
+/**
+ * Astro middleware for Payload Live Preview.
+ *
+ * Responsibilities (per request):
+ *
+ *   1. Generate a per-response CSP nonce and stash it on
+ *      `Astro.locals.livePreviewNonce` so consumers can reference it.
+ *   2. On **preview requests only** (see `isPreviewRequest`), rewrite
+ *      the HTML response to inject the live-preview `<script>` tag.
+ *      Normal production traffic streams through untouched — no
+ *      buffering, no extra bytes.
+ *   3. On preview requests, merge `frame-ancestors` into the
+ *      `Content-Security-Policy` header so the Payload admin may embed
+ *      the page. Full `script-src` nonce management is opt-in via
+ *      `manageCsp: 'full'`.
+ *
+ * Prerendered pages are skipped entirely: Astro runs middleware at
+ * build time for those, where per-request nonces and response headers
+ * are meaningless.
+ *
+ * @module @adapters/astro/middleware
+ */
+
+type MiddlewareNext = () => Promise<Response>;
+interface MiddlewareContext {
+    readonly request: Request;
+    readonly locals: Record<string, unknown>;
+    /** Present in Astro ≥ 5: `true` while prerendering at build time. */
+    readonly isPrerendered?: boolean;
+}
+type LivePreviewMiddleware = (context: MiddlewareContext, next: MiddlewareNext) => Promise<Response>;
+/**
+ * Key on `Astro.locals` carrying the request-scoped nonce. Consumers
+ * can read `Astro.locals.livePreviewNonce` from `.astro` templates to
+ * set the `nonce` attribute on their own scripts.
+ */
+declare const NONCE_LOCALS_KEY = "livePreviewNonce";
+/**
+ * Build the Astro-compatible middleware. Register it in
+ * `src/middleware.ts`:
+ *
+ * ```ts
+ * import { createLivePreviewMiddleware } from 'payload-live-preview/astro';
+ * export const onRequest = createLivePreviewMiddleware({
+ *   allowedOrigins: [import.meta.env.PUBLIC_PAYLOAD_ADMIN_ORIGIN],
+ * });
+ * ```
+ */
+declare function createLivePreviewMiddleware(options?: LivePreviewAstroOptions): LivePreviewMiddleware;
+
+export { type LivePreviewAstroOptions as L, NONCE_LOCALS_KEY as N, type LivePreviewMiddleware as a, createLivePreviewMiddleware as c };

package/dist/payload.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+// src/payload/index.ts
+function buildLivePreviewUrl(options) {
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const fallback = options.fallback ?? "/";
+  const previewParam = options.previewParam === void 0 ? "preview" : options.previewParam;
+  return (args) => {
+    const locale = normaliseLocale(args.locale);
+    const context = { data: args.data, locale };
+    const resolver = (args.collectionConfig !== void 0 ? options.collections?.[args.collectionConfig.slug] : void 0) ?? (args.globalConfig !== void 0 ? options.globals?.[args.globalConfig.slug] : void 0);
+    let path = fallback;
+    if (resolver !== void 0) {
+      const resolved = typeof resolver === "function" ? resolver(context) : resolver;
+      if (resolved.length > 0) path = resolved;
+    }
+    if (!path.startsWith("/")) path = `/${path}`;
+    if (previewParam === null) return `${base}${path}`;
+    const separator = path.includes("?") ? "&" : "?";
+    return `${base}${path}${separator}${previewParam}=true`;
+  };
+}
+function normaliseLocale(locale) {
+  if (locale === void 0) return void 0;
+  if (typeof locale === "string") return locale.length > 0 ? locale : void 0;
+  return locale.code.length > 0 ? locale.code : void 0;
+}
+
+exports.buildLivePreviewUrl = buildLivePreviewUrl;
+//# sourceMappingURL=payload.cjs.map
+//# sourceMappingURL=payload.cjs.map

package/dist/payload.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/payload/index.ts"],"names":[],"mappings":";;;AAmFO,SAAS,oBACd,OAAA,EACsC;AACtC,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,OAAA,CAAQ,OAAA,CAAQ,QAAQ,EAAE,CAAA;AAC/C,EAAA,MAAM,QAAA,GAAW,QAAQ,QAAA,IAAY,GAAA;AACrC,EAAA,MAAM,YAAA,GAAe,OAAA,CAAQ,YAAA,KAAiB,MAAA,GAAY,YAAY,OAAA,CAAQ,YAAA;AAE9E,EAAA,OAAO,CAAC,IAAA,KAAS;AACf,IAAA,MAAM,MAAA,GAAS,eAAA,CAAgB,IAAA,CAAK,MAAM,CAAA;AAC1C,IAAA,MAAM,OAAA,GAA+B,EAAE,IAAA,EAAM,IAAA,CAAK,MAAM,MAAA,EAAO;AAE/D,IAAA,MAAM,YACH,IAAA,CAAK,gBAAA,KAAqB,SACvB,OAAA,CAAQ,WAAA,GAAc,KAAK,gBAAA,CAAiB,IAAI,IAChD,MAAA,MACH,IAAA,CAAK,iBAAiB,MAAA,GAAY,OAAA,CAAQ,UAAU,IAAA,CAAK,YAAA,CAAa,IAAI,CAAA,GAAI,MAAA,CAAA;AAEjF,IAAA,IAAI,IAAA,GAAO,QAAA;AACX,IAAA,IAAI,aAAa,MAAA,EAAW;AAC1B,MAAA,MAAM,WAAW,OAAO,QAAA,KAAa,UAAA,GAAa,QAAA,CAAS,OAAO,CAAA,GAAI,QAAA;AACtE,MAAA,IAAI,QAAA,CAAS,MAAA,GAAS,CAAA,EAAG,IAAA,GAAO,QAAA;AAAA,IAClC;AACA,IAAA,IAAI,CAAC,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA,EAAG,IAAA,GAAO,IAAI,IAAI,CAAA,CAAA;AAE1C,IAAA,IAAI,iBAAiB,IAAA,EAAM,OAAO,CAAA,EAAG,IAAI,GAAG,IAAI,CAAA,CAAA;AAChD,IAAA,MAAM,SAAA,GAAY,IAAA,CAAK,QAAA,CAAS,GAAG,IAAI,GAAA,GAAM,GAAA;AAC7C,IAAA,OAAO,GAAG,IAAI,CAAA,EAAG,IAAI,CAAA,EAAG,SAAS,GAAG,YAAY,CAAA,KAAA,CAAA;AAAA,EAClD,CAAA;AACF;AAEA,SAAS,gBAAgB,MAAA,EAA0D;AACjF,EAAA,IAAI,MAAA,KAAW,QAAW,OAAO,MAAA;AACjC,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,SAAiB,MAAA,CAAO,MAAA,GAAS,IAAI,MAAA,GAAS,MAAA;AACpE,EAAA,OAAO,MAAA,CAAO,IAAA,CAAK,MAAA,GAAS,CAAA,GAAI,OAAO,IAAA,GAAO,MAAA;AAChD","file":"payload.cjs","sourcesContent":["/**\n * Backend-side helpers for `payload.config.ts`.\n *\n * Payload's `admin.livePreview.url` callback maps the document being\n * edited to the frontend URL that should be shown in the preview\n * iframe. In practice every project hand-writes the same lookup-table\n * boilerplate (global → path, collection → localized route, fallback\n * when a new draft has no slug yet). `buildLivePreviewUrl` packages\n * that pattern.\n *\n * This module is dependency-free and framework-agnostic — it does not\n * import `payload`, it just produces a function with the documented\n * callback shape.\n *\n * ```ts\n * // payload.config.ts\n * import { buildLivePreviewUrl } from 'payload-live-preview/payload';\n *\n * admin: {\n *   livePreview: {\n *     url: buildLivePreviewUrl({\n *       baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:4321',\n *       collections: {\n *         services: ({ data, locale }) => `/${locale}/services/${String(data.slug ?? '')}`,\n *         posts: ({ data }) => `/blog/${String(data.slug ?? '')}`,\n *       },\n *       globals: {\n *         homepage: '/',\n *         contact: ({ locale }) => `/${locale}/contact`,\n *       },\n *       fallback: '/',\n *     }),\n *     collections: ['services', 'posts'],\n *     globals: ['homepage', 'contact'],\n *   },\n * }\n * ```\n *\n * @module @payload\n */\n\n/** Arguments Payload passes to `admin.livePreview.url`. */\nexport interface LivePreviewUrlArgs {\n  readonly data: Record<string, unknown>;\n  readonly locale?: string | { readonly code: string };\n  readonly collectionConfig?: { readonly slug: string };\n  readonly globalConfig?: { readonly slug: string };\n  readonly [extra: string]: unknown;\n}\n\n/** Context handed to per-slug path resolvers. */\nexport interface PathResolverContext {\n  readonly data: Record<string, unknown>;\n  /** Normalised locale code (string), or `undefined`. */\n  readonly locale: string | undefined;\n}\n\nexport type PathResolver = string | ((context: PathResolverContext) => string);\n\nexport interface BuildLivePreviewUrlOptions {\n  /** Frontend origin, e.g. `https://site.example` (no trailing slash needed). */\n  readonly baseUrl: string;\n  /** Per-collection path resolvers keyed by collection slug. */\n  readonly collections?: Readonly<Record<string, PathResolver>>;\n  /** Per-global path resolvers keyed by global slug. */\n  readonly globals?: Readonly<Record<string, PathResolver>>;\n  /**\n   * Path used when no resolver matches, or when a resolver returns an\n   * empty string (e.g. a brand-new draft without a slug). Default `/`.\n   */\n  readonly fallback?: string;\n  /**\n   * Query parameter appended so the frontend can recognise the request\n   * as a preview (`isPreviewRequest` checks it). Set `null` to disable.\n   * Default `'preview'` → `?preview=true`.\n   */\n  readonly previewParam?: string | null;\n}\n\n/**\n * Build an `admin.livePreview.url` callback from declarative slug →\n * path mappings.\n */\nexport function buildLivePreviewUrl(\n  options: BuildLivePreviewUrlOptions,\n): (args: LivePreviewUrlArgs) => string {\n  const base = options.baseUrl.replace(/\\/+$/, '');\n  const fallback = options.fallback ?? '/';\n  const previewParam = options.previewParam === undefined ? 'preview' : options.previewParam;\n\n  return (args) => {\n    const locale = normaliseLocale(args.locale);\n    const context: PathResolverContext = { data: args.data, locale };\n\n    const resolver =\n      (args.collectionConfig !== undefined\n        ? options.collections?.[args.collectionConfig.slug]\n        : undefined) ??\n      (args.globalConfig !== undefined ? options.globals?.[args.globalConfig.slug] : undefined);\n\n    let path = fallback;\n    if (resolver !== undefined) {\n      const resolved = typeof resolver === 'function' ? resolver(context) : resolver;\n      if (resolved.length > 0) path = resolved;\n    }\n    if (!path.startsWith('/')) path = `/${path}`;\n\n    if (previewParam === null) return `${base}${path}`;\n    const separator = path.includes('?') ? '&' : '?';\n    return `${base}${path}${separator}${previewParam}=true`;\n  };\n}\n\nfunction normaliseLocale(locale: LivePreviewUrlArgs['locale']): string | undefined {\n  if (locale === undefined) return undefined;\n  if (typeof locale === 'string') return locale.length > 0 ? locale : undefined;\n  return locale.code.length > 0 ? locale.code : undefined;\n}\n"]}

package/dist/payload.d.cts

@@ -0,0 +1,87 @@
+/**
+ * Backend-side helpers for `payload.config.ts`.
+ *
+ * Payload's `admin.livePreview.url` callback maps the document being
+ * edited to the frontend URL that should be shown in the preview
+ * iframe. In practice every project hand-writes the same lookup-table
+ * boilerplate (global → path, collection → localized route, fallback
+ * when a new draft has no slug yet). `buildLivePreviewUrl` packages
+ * that pattern.
+ *
+ * This module is dependency-free and framework-agnostic — it does not
+ * import `payload`, it just produces a function with the documented
+ * callback shape.
+ *
+ * ```ts
+ * // payload.config.ts
+ * import { buildLivePreviewUrl } from 'payload-live-preview/payload';
+ *
+ * admin: {
+ *   livePreview: {
+ *     url: buildLivePreviewUrl({
+ *       baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:4321',
+ *       collections: {
+ *         services: ({ data, locale }) => `/${locale}/services/${String(data.slug ?? '')}`,
+ *         posts: ({ data }) => `/blog/${String(data.slug ?? '')}`,
+ *       },
+ *       globals: {
+ *         homepage: '/',
+ *         contact: ({ locale }) => `/${locale}/contact`,
+ *       },
+ *       fallback: '/',
+ *     }),
+ *     collections: ['services', 'posts'],
+ *     globals: ['homepage', 'contact'],
+ *   },
+ * }
+ * ```
+ *
+ * @module @payload
+ */
+/** Arguments Payload passes to `admin.livePreview.url`. */
+interface LivePreviewUrlArgs {
+    readonly data: Record<string, unknown>;
+    readonly locale?: string | {
+        readonly code: string;
+    };
+    readonly collectionConfig?: {
+        readonly slug: string;
+    };
+    readonly globalConfig?: {
+        readonly slug: string;
+    };
+    readonly [extra: string]: unknown;
+}
+/** Context handed to per-slug path resolvers. */
+interface PathResolverContext {
+    readonly data: Record<string, unknown>;
+    /** Normalised locale code (string), or `undefined`. */
+    readonly locale: string | undefined;
+}
+type PathResolver = string | ((context: PathResolverContext) => string);
+interface BuildLivePreviewUrlOptions {
+    /** Frontend origin, e.g. `https://site.example` (no trailing slash needed). */
+    readonly baseUrl: string;
+    /** Per-collection path resolvers keyed by collection slug. */
+    readonly collections?: Readonly<Record<string, PathResolver>>;
+    /** Per-global path resolvers keyed by global slug. */
+    readonly globals?: Readonly<Record<string, PathResolver>>;
+    /**
+     * Path used when no resolver matches, or when a resolver returns an
+     * empty string (e.g. a brand-new draft without a slug). Default `/`.
+     */
+    readonly fallback?: string;
+    /**
+     * Query parameter appended so the frontend can recognise the request
+     * as a preview (`isPreviewRequest` checks it). Set `null` to disable.
+     * Default `'preview'` → `?preview=true`.
+     */
+    readonly previewParam?: string | null;
+}
+/**
+ * Build an `admin.livePreview.url` callback from declarative slug →
+ * path mappings.
+ */
+declare function buildLivePreviewUrl(options: BuildLivePreviewUrlOptions): (args: LivePreviewUrlArgs) => string;
+
+export { type BuildLivePreviewUrlOptions, type LivePreviewUrlArgs, type PathResolver, type PathResolverContext, buildLivePreviewUrl };

package/dist/payload.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Backend-side helpers for `payload.config.ts`.
+ *
+ * Payload's `admin.livePreview.url` callback maps the document being
+ * edited to the frontend URL that should be shown in the preview
+ * iframe. In practice every project hand-writes the same lookup-table
+ * boilerplate (global → path, collection → localized route, fallback
+ * when a new draft has no slug yet). `buildLivePreviewUrl` packages
+ * that pattern.
+ *
+ * This module is dependency-free and framework-agnostic — it does not
+ * import `payload`, it just produces a function with the documented
+ * callback shape.
+ *
+ * ```ts
+ * // payload.config.ts
+ * import { buildLivePreviewUrl } from 'payload-live-preview/payload';
+ *
+ * admin: {
+ *   livePreview: {
+ *     url: buildLivePreviewUrl({
+ *       baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:4321',
+ *       collections: {
+ *         services: ({ data, locale }) => `/${locale}/services/${String(data.slug ?? '')}`,
+ *         posts: ({ data }) => `/blog/${String(data.slug ?? '')}`,
+ *       },
+ *       globals: {
+ *         homepage: '/',
+ *         contact: ({ locale }) => `/${locale}/contact`,
+ *       },
+ *       fallback: '/',
+ *     }),
+ *     collections: ['services', 'posts'],
+ *     globals: ['homepage', 'contact'],
+ *   },
+ * }
+ * ```
+ *
+ * @module @payload
+ */
+/** Arguments Payload passes to `admin.livePreview.url`. */
+interface LivePreviewUrlArgs {
+    readonly data: Record<string, unknown>;
+    readonly locale?: string | {
+        readonly code: string;
+    };
+    readonly collectionConfig?: {
+        readonly slug: string;
+    };
+    readonly globalConfig?: {
+        readonly slug: string;
+    };
+    readonly [extra: string]: unknown;
+}
+/** Context handed to per-slug path resolvers. */
+interface PathResolverContext {
+    readonly data: Record<string, unknown>;
+    /** Normalised locale code (string), or `undefined`. */
+    readonly locale: string | undefined;
+}
+type PathResolver = string | ((context: PathResolverContext) => string);
+interface BuildLivePreviewUrlOptions {
+    /** Frontend origin, e.g. `https://site.example` (no trailing slash needed). */
+    readonly baseUrl: string;
+    /** Per-collection path resolvers keyed by collection slug. */
+    readonly collections?: Readonly<Record<string, PathResolver>>;
+    /** Per-global path resolvers keyed by global slug. */
+    readonly globals?: Readonly<Record<string, PathResolver>>;
+    /**
+     * Path used when no resolver matches, or when a resolver returns an
+     * empty string (e.g. a brand-new draft without a slug). Default `/`.
+     */
+    readonly fallback?: string;
+    /**
+     * Query parameter appended so the frontend can recognise the request
+     * as a preview (`isPreviewRequest` checks it). Set `null` to disable.
+     * Default `'preview'` → `?preview=true`.
+     */
+    readonly previewParam?: string | null;
+}
+/**
+ * Build an `admin.livePreview.url` callback from declarative slug →
+ * path mappings.
+ */
+declare function buildLivePreviewUrl(options: BuildLivePreviewUrlOptions): (args: LivePreviewUrlArgs) => string;
+
+export { type BuildLivePreviewUrlOptions, type LivePreviewUrlArgs, type PathResolver, type PathResolverContext, buildLivePreviewUrl };

package/dist/payload.js

@@ -0,0 +1,29 @@
+// src/payload/index.ts
+function buildLivePreviewUrl(options) {
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const fallback = options.fallback ?? "/";
+  const previewParam = options.previewParam === void 0 ? "preview" : options.previewParam;
+  return (args) => {
+    const locale = normaliseLocale(args.locale);
+    const context = { data: args.data, locale };
+    const resolver = (args.collectionConfig !== void 0 ? options.collections?.[args.collectionConfig.slug] : void 0) ?? (args.globalConfig !== void 0 ? options.globals?.[args.globalConfig.slug] : void 0);
+    let path = fallback;
+    if (resolver !== void 0) {
+      const resolved = typeof resolver === "function" ? resolver(context) : resolver;
+      if (resolved.length > 0) path = resolved;
+    }
+    if (!path.startsWith("/")) path = `/${path}`;
+    if (previewParam === null) return `${base}${path}`;
+    const separator = path.includes("?") ? "&" : "?";
+    return `${base}${path}${separator}${previewParam}=true`;
+  };
+}
+function normaliseLocale(locale) {
+  if (locale === void 0) return void 0;
+  if (typeof locale === "string") return locale.length > 0 ? locale : void 0;
+  return locale.code.length > 0 ? locale.code : void 0;
+}
+
+export { buildLivePreviewUrl };
+//# sourceMappingURL=payload.js.map
+//# sourceMappingURL=payload.js.map

package/dist/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/payload/index.ts"],"names":[],"mappings":";AAmFO,SAAS,oBACd,OAAA,EACsC;AACtC,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,OAAA,CAAQ,OAAA,CAAQ,QAAQ,EAAE,CAAA;AAC/C,EAAA,MAAM,QAAA,GAAW,QAAQ,QAAA,IAAY,GAAA;AACrC,EAAA,MAAM,YAAA,GAAe,OAAA,CAAQ,YAAA,KAAiB,MAAA,GAAY,YAAY,OAAA,CAAQ,YAAA;AAE9E,EAAA,OAAO,CAAC,IAAA,KAAS;AACf,IAAA,MAAM,MAAA,GAAS,eAAA,CAAgB,IAAA,CAAK,MAAM,CAAA;AAC1C,IAAA,MAAM,OAAA,GAA+B,EAAE,IAAA,EAAM,IAAA,CAAK,MAAM,MAAA,EAAO;AAE/D,IAAA,MAAM,YACH,IAAA,CAAK,gBAAA,KAAqB,SACvB,OAAA,CAAQ,WAAA,GAAc,KAAK,gBAAA,CAAiB,IAAI,IAChD,MAAA,MACH,IAAA,CAAK,iBAAiB,MAAA,GAAY,OAAA,CAAQ,UAAU,IAAA,CAAK,YAAA,CAAa,IAAI,CAAA,GAAI,MAAA,CAAA;AAEjF,IAAA,IAAI,IAAA,GAAO,QAAA;AACX,IAAA,IAAI,aAAa,MAAA,EAAW;AAC1B,MAAA,MAAM,WAAW,OAAO,QAAA,KAAa,UAAA,GAAa,QAAA,CAAS,OAAO,CAAA,GAAI,QAAA;AACtE,MAAA,IAAI,QAAA,CAAS,MAAA,GAAS,CAAA,EAAG,IAAA,GAAO,QAAA;AAAA,IAClC;AACA,IAAA,IAAI,CAAC,IAAA,CAAK,UAAA,CAAW,GAAG,CAAA,EAAG,IAAA,GAAO,IAAI,IAAI,CAAA,CAAA;AAE1C,IAAA,IAAI,iBAAiB,IAAA,EAAM,OAAO,CAAA,EAAG,IAAI,GAAG,IAAI,CAAA,CAAA;AAChD,IAAA,MAAM,SAAA,GAAY,IAAA,CAAK,QAAA,CAAS,GAAG,IAAI,GAAA,GAAM,GAAA;AAC7C,IAAA,OAAO,GAAG,IAAI,CAAA,EAAG,IAAI,CAAA,EAAG,SAAS,GAAG,YAAY,CAAA,KAAA,CAAA;AAAA,EAClD,CAAA;AACF;AAEA,SAAS,gBAAgB,MAAA,EAA0D;AACjF,EAAA,IAAI,MAAA,KAAW,QAAW,OAAO,MAAA;AACjC,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,SAAiB,MAAA,CAAO,MAAA,GAAS,IAAI,MAAA,GAAS,MAAA;AACpE,EAAA,OAAO,MAAA,CAAO,IAAA,CAAK,MAAA,GAAS,CAAA,GAAI,OAAO,IAAA,GAAO,MAAA;AAChD","file":"payload.js","sourcesContent":["/**\n * Backend-side helpers for `payload.config.ts`.\n *\n * Payload's `admin.livePreview.url` callback maps the document being\n * edited to the frontend URL that should be shown in the preview\n * iframe. In practice every project hand-writes the same lookup-table\n * boilerplate (global → path, collection → localized route, fallback\n * when a new draft has no slug yet). `buildLivePreviewUrl` packages\n * that pattern.\n *\n * This module is dependency-free and framework-agnostic — it does not\n * import `payload`, it just produces a function with the documented\n * callback shape.\n *\n * ```ts\n * // payload.config.ts\n * import { buildLivePreviewUrl } from 'payload-live-preview/payload';\n *\n * admin: {\n *   livePreview: {\n *     url: buildLivePreviewUrl({\n *       baseUrl: process.env.FRONTEND_URL ?? 'http://localhost:4321',\n *       collections: {\n *         services: ({ data, locale }) => `/${locale}/services/${String(data.slug ?? '')}`,\n *         posts: ({ data }) => `/blog/${String(data.slug ?? '')}`,\n *       },\n *       globals: {\n *         homepage: '/',\n *         contact: ({ locale }) => `/${locale}/contact`,\n *       },\n *       fallback: '/',\n *     }),\n *     collections: ['services', 'posts'],\n *     globals: ['homepage', 'contact'],\n *   },\n * }\n * ```\n *\n * @module @payload\n */\n\n/** Arguments Payload passes to `admin.livePreview.url`. */\nexport interface LivePreviewUrlArgs {\n  readonly data: Record<string, unknown>;\n  readonly locale?: string | { readonly code: string };\n  readonly collectionConfig?: { readonly slug: string };\n  readonly globalConfig?: { readonly slug: string };\n  readonly [extra: string]: unknown;\n}\n\n/** Context handed to per-slug path resolvers. */\nexport interface PathResolverContext {\n  readonly data: Record<string, unknown>;\n  /** Normalised locale code (string), or `undefined`. */\n  readonly locale: string | undefined;\n}\n\nexport type PathResolver = string | ((context: PathResolverContext) => string);\n\nexport interface BuildLivePreviewUrlOptions {\n  /** Frontend origin, e.g. `https://site.example` (no trailing slash needed). */\n  readonly baseUrl: string;\n  /** Per-collection path resolvers keyed by collection slug. */\n  readonly collections?: Readonly<Record<string, PathResolver>>;\n  /** Per-global path resolvers keyed by global slug. */\n  readonly globals?: Readonly<Record<string, PathResolver>>;\n  /**\n   * Path used when no resolver matches, or when a resolver returns an\n   * empty string (e.g. a brand-new draft without a slug). Default `/`.\n   */\n  readonly fallback?: string;\n  /**\n   * Query parameter appended so the frontend can recognise the request\n   * as a preview (`isPreviewRequest` checks it). Set `null` to disable.\n   * Default `'preview'` → `?preview=true`.\n   */\n  readonly previewParam?: string | null;\n}\n\n/**\n * Build an `admin.livePreview.url` callback from declarative slug →\n * path mappings.\n */\nexport function buildLivePreviewUrl(\n  options: BuildLivePreviewUrlOptions,\n): (args: LivePreviewUrlArgs) => string {\n  const base = options.baseUrl.replace(/\\/+$/, '');\n  const fallback = options.fallback ?? '/';\n  const previewParam = options.previewParam === undefined ? 'preview' : options.previewParam;\n\n  return (args) => {\n    const locale = normaliseLocale(args.locale);\n    const context: PathResolverContext = { data: args.data, locale };\n\n    const resolver =\n      (args.collectionConfig !== undefined\n        ? options.collections?.[args.collectionConfig.slug]\n        : undefined) ??\n      (args.globalConfig !== undefined ? options.globals?.[args.globalConfig.slug] : undefined);\n\n    let path = fallback;\n    if (resolver !== undefined) {\n      const resolved = typeof resolver === 'function' ? resolver(context) : resolver;\n      if (resolved.length > 0) path = resolved;\n    }\n    if (!path.startsWith('/')) path = `/${path}`;\n\n    if (previewParam === null) return `${base}${path}`;\n    const separator = path.includes('?') ? '&' : '?';\n    return `${base}${path}${separator}${previewParam}=true`;\n  };\n}\n\nfunction normaliseLocale(locale: LivePreviewUrlArgs['locale']): string | undefined {\n  if (locale === undefined) return undefined;\n  if (typeof locale === 'string') return locale.length > 0 ? locale : undefined;\n  return locale.code.length > 0 ? locale.code : undefined;\n}\n"]}

package/dist/preview-request-DAvxm18T.d.cts

@@ -0,0 +1,68 @@
+/**
+ * Server-side preview-request detection.
+ *
+ * The live-preview runtime only ever activates inside the Payload
+ * admin's iframe, but the *server* still has to decide whether to
+ * inject the (sizeable) inline script into a given HTML response.
+ * Injecting it into every page for every visitor buffers every
+ * response and ships dead bytes to production traffic — so adapters
+ * gate injection on this predicate by default, and consumers with
+ * hand-rolled middleware can import it directly.
+ *
+ * A request counts as a preview when any of these hold:
+ *
+ *   1. A preview query parameter is present (`?preview=true`,
+ *      `?draft=true`, `?livePreview=true` — configurable).
+ *   2. `Sec-Fetch-Dest: iframe` — the document is being loaded as an
+ *      iframe, which is exactly how the Payload admin embeds it.
+ *      (Sent by all evergreen browsers; absence never *excludes* a
+ *      request, presence includes it.)
+ *   3. The `Referer` points at one of the given admin origins.
+ *
+ * @module @adapters/shared/preview-request
+ */
+/** The individual signals the predicate can consider. */
+type PreviewSignal = 'query' | 'fetch-dest' | 'referer';
+interface PreviewRequestOptions {
+    /**
+     * Which signals count as "this is a preview request". Default: all
+     * three. High-security setups that must never relax framing headers
+     * for unsolicited iframe loads can restrict to `['query']` — then
+     * only an explicit `?preview=true` (e.g. from `buildLivePreviewUrl`)
+     * activates preview handling.
+     */
+    readonly signals?: readonly PreviewSignal[];
+    /**
+     * Query parameters (with values `true` or `1`) that mark a request
+     * as a preview. Default: `['preview', 'draft', 'livePreview']`.
+     */
+    readonly queryParams?: readonly string[];
+    /**
+     * Treat `Sec-Fetch-Dest: iframe` as a preview signal. Default `true`.
+     * Legacy alias for excluding `'fetch-dest'` from `signals`.
+     */
+    readonly checkFetchDest?: boolean;
+    /**
+     * Admin origins whose `Referer` marks a request as a preview,
+     * e.g. `['https://cms.example.com']`.
+     */
+    readonly adminOrigins?: readonly string[];
+}
+/**
+ * The minimal request surface the predicate needs. The standard
+ * `Request` satisfies it structurally, and server frameworks without
+ * fetch-style requests (e.g. Nitro/H3) can supply a tiny shim.
+ */
+interface PreviewRequestLike {
+    readonly url: string;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Decide whether `request` is a live-preview request. See the module
+ * docblock for the exact signals.
+ */
+declare function isPreviewRequest(request: PreviewRequestLike, options?: PreviewRequestOptions): boolean;
+
+export { type PreviewRequestLike as P, type PreviewRequestOptions as a, isPreviewRequest as i };