feat: add support for sanity-preview-perspective in loadQuery

codercatdev · codercatdev · commit 08554b7a4b4b · 2026-03-17T19:10:04.000-04:00
- Enhanced multiple page components to accept a new `perspective` parameter for improved visual editing.
- Updated the `loadQuery` function to handle the `perspective` parameter, allowing for dynamic content fetching based on the selected preview perspective.
- Implemented message handling in visual editing script to synchronize perspective changes from the Studio.
diff --git a/apps/web/src/pages/[slug].astro b/apps/web/src/pages/[slug].astro
@@ -16,7 +16,8 @@ if (reservedSlugs.includes(slug!)) {
 }
 
 const draftMode = Astro.cookies.has("__sanity_preview");
-const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug }, draftMode });
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
+const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug }, draftMode, perspective });
 
 if (!page) {
   return new Response(null, { status: 404 });
diff --git a/apps/web/src/pages/author/[slug].astro b/apps/web/src/pages/author/[slug].astro
@@ -9,7 +9,8 @@ export const prerender = false;
 
 const { slug } = Astro.params;
 const draftMode = Astro.cookies.has("__sanity_preview");
-const { data: author } = await loadQuery<any>({ query: authorQuery, params: { slug }, draftMode });
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
+const { data: author } = await loadQuery<any>({ query: authorQuery, params: { slug }, draftMode, perspective });
 
 if (!author) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/authors.astro b/apps/web/src/pages/authors.astro
@@ -14,8 +14,9 @@ const perPage = 12;
 const offset = (page - 1) * perPage;
 
 const draftMode = Astro.cookies.has("__sanity_preview");
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
 const [itemsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: authorListQuery, params: { offset, end: offset + perPage }, draftMode }),
+  loadQuery<any[]>({ query: authorListQuery, params: { offset, end: offset + perPage }, draftMode, perspective }),
   sanityFetch<number>(authorCountQuery),
 ]);
 const items = itemsResult.data;
diff --git a/apps/web/src/pages/blog.astro b/apps/web/src/pages/blog.astro
@@ -17,8 +17,9 @@ const perPage = 12;
 const offset = (page - 1) * perPage;
 
 const draftMode = Astro.cookies.has("__sanity_preview");
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
 const [postsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: postListQuery, params: { offset, end: offset + perPage }, draftMode }),
+  loadQuery<any[]>({ query: postListQuery, params: { offset, end: offset + perPage }, draftMode, perspective }),
   sanityFetch<number>(postCountQuery),
 ]);
 const posts = postsResult.data;
diff --git a/apps/web/src/pages/guest/[slug].astro b/apps/web/src/pages/guest/[slug].astro
@@ -9,7 +9,8 @@ export const prerender = false;
 
 const { slug } = Astro.params;
 const draftMode = Astro.cookies.has("__sanity_preview");
-const { data: guest } = await loadQuery<any>({ query: guestQuery, params: { slug }, draftMode });
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
+const { data: guest } = await loadQuery<any>({ query: guestQuery, params: { slug }, draftMode, perspective });
 
 if (!guest) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/guests.astro b/apps/web/src/pages/guests.astro
@@ -14,8 +14,9 @@ const perPage = 12;
 const offset = (page - 1) * perPage;
 
 const draftMode = Astro.cookies.has("__sanity_preview");
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
 const [itemsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: guestListQuery, params: { offset, end: offset + perPage }, draftMode }),
+  loadQuery<any[]>({ query: guestListQuery, params: { offset, end: offset + perPage }, draftMode, perspective }),
   sanityFetch<number>(guestCountQuery),
 ]);
 const items = itemsResult.data;
diff --git a/apps/web/src/pages/index.astro b/apps/web/src/pages/index.astro
@@ -11,7 +11,8 @@ import { homePageQuery } from "@/lib/queries";
 export const prerender = false;
 
 const draftMode = Astro.cookies.has("__sanity_preview");
-const { data: homePage } = await loadQuery<any>({ query: homePageQuery, draftMode });
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
+const { data: homePage } = await loadQuery<any>({ query: homePageQuery, draftMode, perspective });
 
 const siteUrl = Astro.url.origin;
 const ogImage = `${siteUrl}/api/og/default.png?title=${encodeURIComponent("CodingCat.dev")}&subtitle=${encodeURIComponent("Purrfect Web Development Tutorials")}`;
diff --git a/apps/web/src/pages/podcast/[slug].astro b/apps/web/src/pages/podcast/[slug].astro
@@ -13,7 +13,8 @@ export const prerender = false;
 
 const { slug } = Astro.params;
 const draftMode = Astro.cookies.has("__sanity_preview");
-const { data: podcast } = await loadQuery<any>({ query: podcastQuery, params: { slug }, draftMode });
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
+const { data: podcast } = await loadQuery<any>({ query: podcastQuery, params: { slug }, draftMode, perspective });
 
 if (!podcast) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/podcasts.astro b/apps/web/src/pages/podcasts.astro
@@ -16,8 +16,9 @@ const perPage = 12;
 const offset = (page - 1) * perPage;
 
 const draftMode = Astro.cookies.has("__sanity_preview");
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
 const [podcastsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: podcastListQuery, params: { offset, end: offset + perPage }, draftMode }),
+  loadQuery<any[]>({ query: podcastListQuery, params: { offset, end: offset + perPage }, draftMode, perspective }),
   sanityFetch<number>(podcastCountQuery),
 ]);
 const podcasts = podcastsResult.data;
diff --git a/apps/web/src/pages/post/[slug].astro b/apps/web/src/pages/post/[slug].astro
@@ -12,7 +12,8 @@ export const prerender = false;
 
 const { slug } = Astro.params;
 const draftMode = Astro.cookies.has("__sanity_preview");
-const { data: post } = await loadQuery<any>({ query: postQuery, params: { slug }, draftMode });
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
+const { data: post } = await loadQuery<any>({ query: postQuery, params: { slug }, draftMode, perspective });
 
 if (!post) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/sponsor/[slug].astro b/apps/web/src/pages/sponsor/[slug].astro
@@ -9,7 +9,8 @@ export const prerender = false;
 
 const { slug } = Astro.params;
 const draftMode = Astro.cookies.has("__sanity_preview");
-const { data: sponsor } = await loadQuery<any>({ query: sponsorQuery, params: { slug }, draftMode });
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
+const { data: sponsor } = await loadQuery<any>({ query: sponsorQuery, params: { slug }, draftMode, perspective });
 
 if (!sponsor) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/sponsors.astro b/apps/web/src/pages/sponsors.astro
@@ -14,8 +14,9 @@ const perPage = 12;
 const offset = (page - 1) * perPage;
 
 const draftMode = Astro.cookies.has("__sanity_preview");
+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;
 const [itemsResult, totalCount] = await Promise.all([
-  loadQuery<any[]>({ query: sponsorListQuery, params: { offset, end: offset + perPage }, draftMode }),
+  loadQuery<any[]>({ query: sponsorListQuery, params: { offset, end: offset + perPage }, draftMode, perspective }),
   sanityFetch<number>(sponsorCountQuery),
 ]);
 const items = itemsResult.data;
diff --git a/apps/web/src/scripts/visual-editing.ts b/apps/web/src/scripts/visual-editing.ts
@@ -1,11 +1,47 @@
 /**
  * Sanity Visual Editing (Plain JS).
  * Loaded only when visual editing is enabled; integrates with History API for Presentation tool.
+ * Listens for presentation/perspective postMessages so switching perspective in Studio reloads
+ * the preview with the correct sanity-preview-perspective URL param (outer context URL change
+ * is not reflected in the iframe, so we must handle the message).
  */
 import { enableVisualEditing } from "@sanity/visual-editing";
 
+function subscribeToPerspectiveChanges(): () => void {
+  const studioOrigin =
+    typeof import.meta.env.PUBLIC_SANITY_STUDIO_URL === "string"
+      ? new URL(import.meta.env.PUBLIC_SANITY_STUDIO_URL).origin
+      : null;
+
+  const handler = (event: MessageEvent) => {
+    if (studioOrigin && event.origin !== studioOrigin) return;
+    const type = event.data?.type;
+    const data = event.data?.data;
+    if (type !== "presentation/perspective" || data == null) return;
+
+    const perspective = data.perspective;
+    if (perspective == null) return;
+
+    const value =
+      typeof perspective === "string"
+        ? perspective
+        : Array.isArray(perspective)
+          ? perspective.join(",")
+          : String(perspective);
+
+    const url = new URL(window.location.href);
+    url.searchParams.set("sanity-preview-perspective", value);
+    window.location.replace(url.toString());
+  };
+
+  window.addEventListener("message", handler);
+  return () => window.removeEventListener("message", handler);
+}
+
 export function run(): () => void {
-  return enableVisualEditing({
+  const teardownPerspective = subscribeToPerspectiveChanges();
+
+  const teardownVisualEditing = enableVisualEditing({
     history: {
       subscribe: (navigate) => {
         const handler = (_event: PopStateEvent) => {
@@ -21,18 +57,32 @@ export function run(): () => void {
         switch (update.type) {
           case "push":
             window.history.pushState(null, "", update.url);
+            // Reload so the new URL (e.g. perspective param) is loaded and server fetches correct data
+            window.location.reload();
             break;
           case "pop":
             window.history.back();
             break;
           case "replace":
             window.history.replaceState(null, "", update.url);
+            window.location.reload();
             break;
           default:
             throw new Error(`Unknown update type: ${(update as { type: string }).type}`);
         }
       },
     },
     zIndex: 1000,
+    refresh: async (payload) => {
+      // Reload preview when user clicks Refresh or when a document is saved in Studio
+      if (payload.source === "manual" || payload.source === "mutation") {
+        window.location.reload();
+      }
+    },
   });
+
+  return () => {
+    teardownPerspective();
+    teardownVisualEditing();
+  };
 }
diff --git a/apps/web/src/utils/sanity.ts b/apps/web/src/utils/sanity.ts
@@ -54,6 +54,12 @@ interface LoadQueryOptions {
   params?: QueryParams;
   /** Per-request draft mode — set from Astro.cookies in page frontmatter */
   draftMode?: boolean;
+  /**
+   * Perspective for preview: "published" | "drafts" | release ID.
+   * Pass Astro.url.searchParams.get("sanity-preview-perspective") when in visual editing
+   * so switching perspective in Studio shows the correct content.
+   */
+  perspective?: string;
 }
 
 /**
@@ -64,40 +70,50 @@ function isDraftMode(draftMode?: boolean): boolean {
   return siteWideVisualEditing || draftMode === true;
 }
 
+/**
+ * Resolve perspective for fetch: use URL param when in preview, else "published".
+ */
+function resolvePerspective(inPreview: boolean, perspectiveParam?: string): string {
+  if (!inPreview) return "published";
+  if (perspectiveParam === "published") return "published";
+  if (perspectiveParam === "drafts" || !perspectiveParam) return "drafts";
+  // Release ID(s) or other perspective
+  return perspectiveParam;
+}
+
 /**
  * Fetch from Sanity with Visual Editing support.
  *
  * For pages: pass `draftMode: Astro.cookies.has('__sanity_preview')`
- * to enable per-request draft mode from the preview cookie.
+ * and `perspective: Astro.url.searchParams.get('sanity-preview-perspective') ?? undefined`
+ * so perspective switches in Studio (published/drafts/releases) show the correct content.
  */
 export async function loadQuery<T>({
   query,
   params,
   draftMode,
+  perspective: perspectiveParam,
 }: LoadQueryOptions): Promise<{ data: T }> {
-  const drafts = isDraftMode(draftMode);
+  const inPreview = isDraftMode(draftMode);
+  const perspective = resolvePerspective(inPreview, perspectiveParam);
 
-  if (drafts && !token) {
+  const needsToken = inPreview && perspective !== "published";
+  if (needsToken && !token) {
     throw new Error(
       "The `SANITY_API_READ_TOKEN` environment variable is required during Visual Editing.",
     );
   }
 
-  const perspective = drafts ? "drafts" : "published";
-
-  const { result, resultSourceMap } = await sanityClient.fetch<T>(
-    query,
-    params ?? {},
-    {
-      filterResponse: false,
-      perspective,
-      resultSourceMap: drafts ? "withKeyArraySelector" : false,
-      stega: drafts,
-      ...(drafts ? { token } : {}),
-      useCdn: !drafts,
-    },
-  );
-
+  const fetchOptions = {
+    filterResponse: false,
+    perspective,
+    resultSourceMap: inPreview ? "withKeyArraySelector" : false,
+    stega: inPreview,
+    ...(needsToken ? { token } : {}),
+    useCdn: perspective === "published",
+  };
+  const response = await sanityClient.fetch<T>(query, params ?? {}, fetchOptions as Parameters<typeof sanityClient.fetch>[2]);
+  const result = (response as { result: T }).result ?? (response as T);
   return { data: result };
 }
 

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,8 @@ if (reservedSlugs.includes(slug!)) {`
`16`	`16`	`}`
`17`	`17`
`18`	`18`	`const draftMode = Astro.cookies.has("__sanity_preview");`
`19`		`-const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug }, draftMode });`
	`19`	`+const perspective = Astro.url.searchParams.get("sanity-preview-perspective") ?? undefined;`
	`20`	`+const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug }, draftMode, perspective });`
`20`	`21`
`21`	`22`	`if (!page) {`
`22`	`23`	`return new Response(null, { status: 404 });`