feat: Sanity Visual Editing — stega, loadQuery, VisualEditing component (#676)

codercatdev · web-flow · commit 74e83a56d4b4 · 2026-03-16T17:27:16.000-04:00
Adds Sanity Visual Editing support for Astro 6:\n\n- loadQuery() helper: draft perspective + stega encoding when enabled, published content when disabled\n- VisualEditing component in BaseLayout (client:only=\"react\", zero server overhead)\n- All 12 content pages updated to use loadQuery for stega support\n- Count queries and RSS/sitemap stay on sanityFetch (stega would corrupt output)\n- Fail-closed: throws if Visual Editing enabled without SANITY_API_READ_TOKEN\n- CF Workers compatible: VisualEditing renders in browser only\n\nTo enable: set PUBLIC_SANITY_VISUAL_EDITING_ENABLED=true + SANITY_API_READ_TOKEN (viewer-level)"
diff --git a/apps/web/astro.config.mjs b/apps/web/astro.config.mjs
@@ -22,6 +22,11 @@ export default defineConfig({
       dataset: sanityDataset,
       useCdn: false,
       apiVersion: "2024-01-01",
+      // Visual Editing: stega encodes edit markers in strings
+      // Studio is standalone (apps/sanity), not embedded — no studioBasePath
+      stega: {
+        studioUrl: "https://codingcat.dev.sanity.studio",
+      },
     }),
     react(),
   ],
diff --git a/apps/web/src/env.d.ts b/apps/web/src/env.d.ts
@@ -1,4 +1,5 @@
 /// <reference path="../.astro/types.d.ts" />
+/// <reference types="@sanity/astro/module" />
 
 declare namespace App {
   interface Locals {
diff --git a/apps/web/src/layouts/BaseLayout.astro b/apps/web/src/layouts/BaseLayout.astro
@@ -1,12 +1,16 @@
 ---
 import "../styles/global.css";
+import { VisualEditing } from "@sanity/astro/visual-editing";
 
 interface Props {
   title: string;
   description?: string;
 }
 
 const { title, description = "CodingCat.dev — Purrfect Web Tutorials" } = Astro.props;
+
+const visualEditingEnabled =
+  import.meta.env.PUBLIC_SANITY_VISUAL_EDITING_ENABLED === "true";
 ---
 
 <!doctype html>
@@ -42,5 +46,7 @@ const { title, description = "CodingCat.dev — Purrfect Web Tutorials" } = Astr
         <p>&copy; {new Date().getFullYear()} CodingCat.dev. All rights reserved.</p>
       </div>
     </footer>
+
+    <VisualEditing enabled={visualEditingEnabled} />
   </body>
 </html>
diff --git a/apps/web/src/pages/[slug].astro b/apps/web/src/pages/[slug].astro
@@ -1,7 +1,7 @@
 ---
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import { PortableText } from "astro-portabletext";
-import { sanityFetch, urlForImage } from "@/utils/sanity";
+import { loadQuery, urlForImage } from "@/utils/sanity";
 import { pageQuery } from "@/lib/queries";
 
 export const prerender = false;
@@ -14,7 +14,7 @@ if (reservedSlugs.includes(slug!)) {
   return Astro.redirect(`/${slug}`);
 }
 
-const page = await sanityFetch<any>(pageQuery, { slug });
+const { data: page } = await loadQuery<any>({ query: pageQuery, params: { slug } });
 
 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
@@ -1,13 +1,13 @@
 ---
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import PersonDetail from "@/components/PersonDetail.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery } from "@/utils/sanity";
 import { authorQuery } from "@/lib/queries";
 
 export const prerender = false;
 
 const { slug } = Astro.params;
-const author = await sanityFetch<any>(authorQuery, { slug });
+const { data: author } = await loadQuery<any>({ query: authorQuery, params: { slug } });
 
 if (!author) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/authors.astro b/apps/web/src/pages/authors.astro
@@ -2,7 +2,7 @@
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import ContentCard from "@/components/ContentCard.astro";
 import Pagination from "@/components/Pagination.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery, sanityFetch } from "@/utils/sanity";
 import { authorListQuery, authorCountQuery } from "@/lib/queries";
 
 export const prerender = false;
@@ -12,10 +12,11 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
-const [items, totalCount] = await Promise.all([
-  sanityFetch<any[]>(authorListQuery, { offset, end: offset + perPage }),
+const [itemsResult, totalCount] = await Promise.all([
+  loadQuery<any[]>({ query: authorListQuery, params: { offset, end: offset + perPage } }),
   sanityFetch<number>(authorCountQuery),
 ]);
+const items = itemsResult.data;
 
 const totalPages = Math.ceil(totalCount / perPage);
 
diff --git a/apps/web/src/pages/blog.astro b/apps/web/src/pages/blog.astro
@@ -2,7 +2,7 @@
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import ContentCard from "@/components/ContentCard.astro";
 import Pagination from "@/components/Pagination.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery, sanityFetch } from "@/utils/sanity";
 import { postListQuery, postCountQuery } from "@/lib/queries";
 
 export const prerender = false;
@@ -13,10 +13,11 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
-const [posts, totalCount] = await Promise.all([
-  sanityFetch<any[]>(postListQuery, { offset, end: offset + perPage }),
+const [postsResult, totalCount] = await Promise.all([
+  loadQuery<any[]>({ query: postListQuery, params: { offset, end: offset + perPage } }),
   sanityFetch<number>(postCountQuery),
 ]);
+const posts = postsResult.data;
 
 const totalPages = Math.ceil(totalCount / perPage);
 
diff --git a/apps/web/src/pages/guest/[slug].astro b/apps/web/src/pages/guest/[slug].astro
@@ -1,13 +1,13 @@
 ---
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import PersonDetail from "@/components/PersonDetail.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery } from "@/utils/sanity";
 import { guestQuery } from "@/lib/queries";
 
 export const prerender = false;
 
 const { slug } = Astro.params;
-const guest = await sanityFetch<any>(guestQuery, { slug });
+const { data: guest } = await loadQuery<any>({ query: guestQuery, params: { slug } });
 
 if (!guest) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/guests.astro b/apps/web/src/pages/guests.astro
@@ -2,7 +2,7 @@
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import ContentCard from "@/components/ContentCard.astro";
 import Pagination from "@/components/Pagination.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery, sanityFetch } from "@/utils/sanity";
 import { guestListQuery, guestCountQuery } from "@/lib/queries";
 
 export const prerender = false;
@@ -12,10 +12,11 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
-const [items, totalCount] = await Promise.all([
-  sanityFetch<any[]>(guestListQuery, { offset, end: offset + perPage }),
+const [itemsResult, totalCount] = await Promise.all([
+  loadQuery<any[]>({ query: guestListQuery, params: { offset, end: offset + perPage } }),
   sanityFetch<number>(guestCountQuery),
 ]);
+const items = itemsResult.data;
 
 const totalPages = Math.ceil(totalCount / perPage);
 
diff --git a/apps/web/src/pages/index.astro b/apps/web/src/pages/index.astro
@@ -1,12 +1,12 @@
 ---
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import ContentCard from "@/components/ContentCard.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery } from "@/utils/sanity";
 import { homePageQuery } from "@/lib/queries";
 
 export const prerender = false;
 
-const homePage = await sanityFetch<any>(homePageQuery);
+const { data: homePage } = await loadQuery<any>({ query: homePageQuery });
 ---
 
 <BaseLayout title="CodingCat.dev — Purrfect Web Tutorials">
diff --git a/apps/web/src/pages/podcast/[slug].astro b/apps/web/src/pages/podcast/[slug].astro
@@ -1,13 +1,13 @@
 ---
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import { PortableText } from "astro-portabletext";
-import { sanityFetch, urlForImage } from "@/utils/sanity";
+import { loadQuery, urlForImage } from "@/utils/sanity";
 import { podcastQuery } from "@/lib/queries";
 
 export const prerender = false;
 
 const { slug } = Astro.params;
-const podcast = await sanityFetch<any>(podcastQuery, { slug });
+const { data: podcast } = await loadQuery<any>({ query: podcastQuery, params: { slug } });
 
 if (!podcast) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/podcasts.astro b/apps/web/src/pages/podcasts.astro
@@ -2,7 +2,7 @@
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import ContentCard from "@/components/ContentCard.astro";
 import Pagination from "@/components/Pagination.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery, sanityFetch } from "@/utils/sanity";
 import { podcastListQuery, podcastCountQuery } from "@/lib/queries";
 
 export const prerender = false;
@@ -13,10 +13,11 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
-const [podcasts, totalCount] = await Promise.all([
-  sanityFetch<any[]>(podcastListQuery, { offset, end: offset + perPage }),
+const [podcastsResult, totalCount] = await Promise.all([
+  loadQuery<any[]>({ query: podcastListQuery, params: { offset, end: offset + perPage } }),
   sanityFetch<number>(podcastCountQuery),
 ]);
+const podcasts = podcastsResult.data;
 
 const totalPages = Math.ceil(totalCount / perPage);
 
diff --git a/apps/web/src/pages/post/[slug].astro b/apps/web/src/pages/post/[slug].astro
@@ -1,13 +1,13 @@
 ---
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import { PortableText } from "astro-portabletext";
-import { sanityFetch, urlForImage } from "@/utils/sanity";
+import { loadQuery, urlForImage } from "@/utils/sanity";
 import { postQuery } from "@/lib/queries";
 
 export const prerender = false;
 
 const { slug } = Astro.params;
-const post = await sanityFetch<any>(postQuery, { slug });
+const { data: post } = await loadQuery<any>({ query: postQuery, params: { slug } });
 
 if (!post) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/sponsor/[slug].astro b/apps/web/src/pages/sponsor/[slug].astro
@@ -1,13 +1,13 @@
 ---
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import PersonDetail from "@/components/PersonDetail.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery } from "@/utils/sanity";
 import { sponsorQuery } from "@/lib/queries";
 
 export const prerender = false;
 
 const { slug } = Astro.params;
-const sponsor = await sanityFetch<any>(sponsorQuery, { slug });
+const { data: sponsor } = await loadQuery<any>({ query: sponsorQuery, params: { slug } });
 
 if (!sponsor) {
   return Astro.redirect("/404");
diff --git a/apps/web/src/pages/sponsors.astro b/apps/web/src/pages/sponsors.astro
@@ -2,7 +2,7 @@
 import BaseLayout from "@/layouts/BaseLayout.astro";
 import ContentCard from "@/components/ContentCard.astro";
 import Pagination from "@/components/Pagination.astro";
-import { sanityFetch } from "@/utils/sanity";
+import { loadQuery, sanityFetch } from "@/utils/sanity";
 import { sponsorListQuery, sponsorCountQuery } from "@/lib/queries";
 
 export const prerender = false;
@@ -12,10 +12,11 @@ const page = Number.isNaN(rawPage) || rawPage < 1 ? 1 : Math.floor(rawPage);
 const perPage = 12;
 const offset = (page - 1) * perPage;
 
-const [items, totalCount] = await Promise.all([
-  sanityFetch<any[]>(sponsorListQuery, { offset, end: offset + perPage }),
+const [itemsResult, totalCount] = await Promise.all([
+  loadQuery<any[]>({ query: sponsorListQuery, params: { offset, end: offset + perPage } }),
   sanityFetch<number>(sponsorCountQuery),
 ]);
+const items = itemsResult.data;
 
 const totalPages = Math.ceil(totalCount / perPage);
 
diff --git a/apps/web/src/utils/sanity.ts b/apps/web/src/utils/sanity.ts
@@ -1,3 +1,18 @@
+/**
+ * Draft-aware Sanity query helper with Visual Editing support.
+ *
+ * When Visual Editing is enabled (PUBLIC_SANITY_VISUAL_EDITING_ENABLED=true):
+ * - Fetches with perspective: "drafts" (shows unpublished content)
+ * - Enables stega encoding (invisible edit markers for click-to-edit overlays)
+ * - Uses SANITY_API_READ_TOKEN for authenticated requests
+ * - Returns resultSourceMap for the Presentation Tool
+ *
+ * When disabled (default):
+ * - Fetches published content only
+ * - No stega encoding (clean strings)
+ * - No token needed (public API)
+ */
+import type { QueryParams } from "sanity";
 import { sanityClient } from "sanity:client";
 import imageUrlBuilder from "@sanity/image-url";
 import type { SanityImageSource } from "@sanity/image-url/lib/types/types";
@@ -8,6 +23,52 @@ export function urlForImage(source: SanityImageSource) {
   return builder.image(source);
 }
 
-export async function sanityFetch<T>(query: string, params?: Record<string, unknown>): Promise<T> {
+const visualEditingEnabled =
+  import.meta.env.PUBLIC_SANITY_VISUAL_EDITING_ENABLED === "true";
+const token = import.meta.env.SANITY_API_READ_TOKEN;
+
+/**
+ * Fetch from Sanity with Visual Editing support.
+ * Use this instead of sanityClient.fetch() directly.
+ */
+export async function loadQuery<T>({
+  query,
+  params,
+}: {
+  query: string;
+  params?: QueryParams;
+}): Promise<{ data: T }> {
+  if (visualEditingEnabled && !token) {
+    throw new Error(
+      "The `SANITY_API_READ_TOKEN` environment variable is required during Visual Editing.",
+    );
+  }
+
+  const perspective = visualEditingEnabled ? "drafts" : "published";
+
+  const { result, resultSourceMap } = await sanityClient.fetch<T>(
+    query,
+    params ?? {},
+    {
+      filterResponse: false,
+      perspective,
+      resultSourceMap: visualEditingEnabled ? "withKeyArraySelector" : false,
+      stega: visualEditingEnabled,
+      ...(visualEditingEnabled ? { token } : {}),
+      useCdn: !visualEditingEnabled,
+    },
+  );
+
+  return { data: result };
+}
+
+/**
+ * Simple fetch for non-visual-editing contexts (RSS, sitemap, etc.)
+ * where stega encoding would corrupt output.
+ */
+export async function sanityFetch<T>(
+  query: string,
+  params?: Record<string, unknown>,
+): Promise<T> {
   return sanityClient.fetch<T>(query, params ?? {});
 }

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`/// <reference path="../.astro/types.d.ts" />`
	`2`	`+/// <reference types="@sanity/astro/module" />`
`2`	`3`
`3`	`4`	`declare namespace App {`
`4`	`5`	`interface Locals {`