bsmnt 0.0.0

package/integrations/sanity/lib/integrations/sanity/README.md

@@ -0,0 +1,144 @@
+# Sanity CMS Integration
+
+Headless CMS with visual editing.
+
+## Environment Variables
+
+```env
+# Required
+NEXT_PUBLIC_SANITY_PROJECT_ID="your-project-id"
+NEXT_PUBLIC_SANITY_DATASET="production"
+
+# Required for Visual Editing & Live Preview
+NEXT_PUBLIC_SANITY_API_READ_TOKEN="your-viewer-token"
+SANITY_PRIVATE_TOKEN="your-editor-token"
+
+# Optional
+NEXT_PUBLIC_SANITY_STUDIO_URL="http://localhost:3000/studio"
+NEXT_PUBLIC_SANITY_API_VERSION="2024-03-15"
+```
+
+> **Note**: Create tokens in [Sanity Dashboard](https://sanity.io/manage) → Your Project → API → Tokens.
+> - **Viewer** token → `NEXT_PUBLIC_SANITY_API_READ_TOKEN`
+> - **Editor** token → `SANITY_PRIVATE_TOKEN`
+
+## Quick Start
+
+1. Access Studio at `/studio`
+2. Create content (Pages, Articles)
+3. Click "Present" for visual editing
+
+## Usage
+
+### Fetching Data
+
+```tsx
+import { sanityFetch } from 'next-sanity/live'
+import { pageQuery } from '@/lib/integrations/sanity/queries'
+
+export default async function Page({ params }) {
+  const { data } = await sanityFetch({ 
+    query: pageQuery, 
+    params: { slug: params.slug } 
+  })
+  return <YourComponent data={data} />
+}
+```
+
+### Build-time Data Fetching
+
+For `generateStaticParams` or other build-time functions, use the client directly:
+
+```tsx
+import { client } from '@/lib/integrations/sanity/client'
+import { allArticlesQuery } from '@/lib/integrations/sanity/queries'
+
+export async function generateStaticParams() {
+  if (!client) return []
+  const data = await client.fetch(allArticlesQuery)
+  return data.map((item) => ({ slug: item.slug?.current ?? '' }))
+}
+```
+
+### Visual Editing
+
+Add `data-sanity` attributes for visual editing:
+
+```tsx
+import { RichText } from '@/lib/integrations/sanity/components/rich-text'
+
+function MyComponent({ data }) {
+  return (
+    <div data-sanity={data._id}>
+      <h1 data-sanity="title">{data.title}</h1>
+      <RichText content={data.content} />
+    </div>
+  )
+}
+```
+
+### Image Handling
+
+```tsx
+import { urlForImage } from '@/lib/integrations/sanity/utils/image'
+import { SanityImage } from '@/components/ui/sanity-image'
+
+// Option 1: Using urlForImage utility
+<img src={urlForImage(image).width(800).url()} alt={image.alt} />
+
+// Option 2: Using SanityImage component
+<SanityImage image={image} maxWidth={800} />
+```
+
+### SEO Metadata
+
+```tsx
+import { generateSanityMetadata } from '@/lib/utils/metadata'
+
+export async function generateMetadata({ params }) {
+  const { data } = await sanityFetch({ query: pageQuery, params })
+  return generateSanityMetadata({ document: data, url: `/page/${params.slug}` })
+}
+```
+
+## Creating New Content Types
+
+1. **Create schema** in `schemaTypes/`:
+
+```typescript
+import { defineField, defineType } from 'sanity'
+
+export const landing = defineType({
+  name: 'landing',
+  type: 'document',
+  fields: [
+    defineField({ name: 'title', type: 'string' }),
+    defineField({ name: 'slug', type: 'slug', options: { source: 'title' } }),
+    defineField({ name: 'content', type: 'richText' }),
+  ],
+})
+```
+
+2. **Add to schema index** in `schemaTypes/index.ts`
+3. **Create query** in `queries.ts`
+4. **Create page** in `app/`
+
+## Caching
+
+- **Draft mode**: Uses `cache: 'no-store'` automatically
+- **Published content**: ISR with `revalidate: 3600`
+- All queries use `cacheSignal()` for automatic cleanup
+
+See [ARCHITECTURE.md](../../../ARCHITECTURE.md) for cache gotchas.
+
+## Troubleshooting
+
+**Visual editor not loading:**
+- Check env vars are set correctly
+- Verify draft mode routes exist (`/api/draft-mode/enable`)
+
+**Content not updating:**
+- Hard refresh browser
+- Check revalidation webhook is configured
+
+**Related**: [Sanity Docs](https://www.sanity.io/docs) · [Parent README](../README.md)

package/integrations/sanity/lib/integrations/sanity/client.ts

@@ -0,0 +1,30 @@
+import { createClient, type SanityClient } from "next-sanity";
+import { isSanityConfigured } from "@/lib/integrations/check-integration";
+import { apiVersion, dataset, privateToken, projectId, studioUrl } from "./env";
+
+/**
+ * Sanity client instance
+ *
+ * Returns null if Sanity is not configured (missing env vars).
+ * Always check with isSanityConfigured() before using.
+ */
+export const client: SanityClient | null = isSanityConfigured()
+	? createClient({
+			projectId,
+			dataset,
+			apiVersion,
+			useCdn: true,
+			perspective: "published",
+			token: privateToken,
+			stega: {
+				studioUrl,
+				filter: (props) => {
+					if (props.sourcePath.at(-1) === "title") {
+						return true;
+					}
+
+					return props.filterDefault(props);
+				},
+			},
+		})
+	: null;

package/integrations/sanity/lib/integrations/sanity/components/disable-draft-mode.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { useDraftModeEnvironment } from "next-sanity/hooks";
+
+export function DisableDraftMode() {
+	const environment = useDraftModeEnvironment();
+	const pathname = usePathname();
+
+	// Only show the disable draft mode button when outside of Presentation Tool
+	if (environment !== "live" && environment !== "unknown") {
+		return null;
+	}
+
+	if (pathname.startsWith("/studio")) {
+		return null;
+	}
+
+	return (
+		<Link
+			href="/api/draft-mode/disable"
+			scroll={false}
+			className="dr-p-4 fixed top-safe right-safe z-50 bg-red font-mono text-primary text-sm uppercase"
+		>
+			Disable Draft Mode
+		</Link>
+	);
+}

package/integrations/sanity/lib/integrations/sanity/components/rich-text.tsx

@@ -0,0 +1,73 @@
+import { PortableText, type PortableTextBlock } from "@portabletext/react";
+import { Link } from "@/components/ui/link";
+import { SanityImage } from "@/components/ui/sanity-image";
+
+interface RichTextProps {
+	content: PortableTextBlock[];
+}
+
+interface LinkFieldData {
+	type: "external" | "internal";
+	url?: string;
+	blank?: boolean;
+	label?: string;
+}
+
+function resolveLinkFieldUrl(linkData: LinkFieldData): string {
+	if (!linkData) return "#";
+
+	// External URL
+	if (linkData.type === "external" && linkData.url) {
+		return linkData.url;
+	}
+
+	// Internal path (like /home, /hubspot, /r3f, etc.)
+	if (linkData.type === "internal" && linkData.url) {
+		return linkData.url;
+	}
+
+	return "#";
+}
+
+export function RichText({ content }: RichTextProps) {
+	if (!content) return null;
+
+	return (
+		<PortableText
+			value={content}
+			components={{
+				types: {
+					image: ({ value }) => <SanityImage image={value} maxWidth={1920} />,
+				},
+				marks: {
+					link: ({ children, value }) => {
+						const href = resolveLinkFieldUrl(value);
+						const isExternal = value?.type === "url";
+
+						return (
+							<Link
+								href={href}
+								target={isExternal && value?.blank ? "_blank" : undefined}
+								rel={
+									isExternal && value?.blank ? "noopener noreferrer" : undefined
+								}
+								data-sanity-edit-target
+							>
+								{children}
+							</Link>
+						);
+					},
+				},
+				block: {
+					h1: ({ children }) => <h1 className="h1">{children}</h1>,
+					h2: ({ children }) => <h2 className="h2">{children}</h2>,
+					h3: ({ children }) => <h3 className="h3">{children}</h3>,
+					h4: ({ children }) => <h4 className="h4">{children}</h4>,
+					h5: ({ children }) => <h5 className="h5">{children}</h5>,
+					h6: ({ children }) => <h6 className="h6">{children}</h6>,
+					normal: ({ children }) => <p className="p">{children}</p>,
+				},
+			}}
+		/>
+	);
+}

package/integrations/sanity/lib/integrations/sanity/env.ts

@@ -0,0 +1,38 @@
+/**
+ * Sanity Environment Configuration
+ *
+ * All values have safe defaults to allow the app to build and run
+ * without Sanity configured. Use isSanityConfigured() to check
+ * if Sanity is properly set up before making API calls.
+ */
+
+/** Sanity API version - defaults to latest stable */
+export const apiVersion =
+	process.env.NEXT_PUBLIC_SANITY_API_VERSION || "2024-03-15";
+
+/** Sanity dataset name - defaults to 'production' */
+export const dataset = process.env.NEXT_PUBLIC_SANITY_DATASET || "production";
+
+/** Sanity project ID - empty string if not configured */
+export const projectId =
+	process.env.NEXT_PUBLIC_SANITY_PROJECT_ID ||
+	process.env.SANITY_STUDIO_PROJECT_ID ||
+	"";
+
+/** Sanity Studio URL for visual editing */
+export const studioUrl =
+	process.env.NODE_ENV === "development"
+		? "http://localhost:3000/studio"
+		: `${process.env.NEXT_PUBLIC_BASE_URL || ""}/studio`;
+
+/** Public read token for client-side queries */
+export const publicToken = process.env.NEXT_PUBLIC_SANITY_API_READ_TOKEN || "";
+
+/** Private token for server-side mutations (optional) */
+export const privateToken = process.env.SANITY_PRIVATE_TOKEN || "";
+
+/** Preview URL for draft mode */
+export const previewURL =
+	process.env.NODE_ENV === "development"
+		? "http://localhost:3000"
+		: process.env.NEXT_PUBLIC_BASE_URL || "";

package/integrations/sanity/lib/integrations/sanity/live/index.tsx

@@ -0,0 +1,34 @@
+import { defineLive } from "next-sanity/live";
+import { isSanityConfigured } from "@/lib/integrations/check-integration";
+import { client } from "../client";
+import { privateToken, publicToken } from "../env";
+
+/**
+ * Sanity Live configuration
+ *
+ * When Sanity is not configured, provides stub implementation
+ * that returns null instead of throwing errors.
+ */
+const isConfigured = isSanityConfigured() && client;
+
+const liveExports = isConfigured
+	? defineLive({
+			// biome-ignore lint/style/noNonNullAssertion: client is checked via isConfigured above
+			client: client!,
+			browserToken: publicToken,
+			serverToken: privateToken,
+		})
+	: null;
+
+/**
+ * Standard sanityFetch function from next-sanity/live.
+ * When Sanity is not configured, returns null data.
+ */
+export const sanityFetch =
+	liveExports?.sanityFetch ?? (async () => ({ data: null }));
+
+/**
+ * Sanity Live component for real-time updates.
+ * Returns null when Sanity is not configured.
+ */
+export const SanityLive = liveExports?.SanityLive ?? (() => null);

package/integrations/sanity/lib/integrations/sanity/queries.ts

@@ -0,0 +1,99 @@
+import { groq } from "next-sanity";
+
+// Helper for rich text content with link projections
+const richTextWithLinks = `
+  content[]{
+    ...,
+    markDefs[]{
+      ...,
+      _type == "link" => {
+        ...,
+        internalLink->{_type, slug, title}
+      }
+    }
+  }
+`;
+
+const linkWithLabel = `
+  link {
+    ...,
+    internalLink->{_type, slug, title}
+  }
+`;
+
+// Page queries
+export const pageQuery = groq`
+  *[_type == "page" && slug.current == $slug][0] {
+    _id,
+    title,
+    slug,
+    ${richTextWithLinks},
+    ${linkWithLabel},
+    metadata,
+    publishedAt,
+    _updatedAt
+  }
+`;
+
+export const pageByIdQuery = groq`
+  *[_type == "page" && _id == $id][0] {
+    _id,
+    title,
+    slug,
+    ${richTextWithLinks},
+    metadata,
+    publishedAt,
+    _updatedAt
+  }
+`;
+
+// Article queries
+export const articleQuery = groq`
+  *[_type == "article" && slug.current == $slug][0] {
+    _id,
+    title,
+    slug,
+    excerpt,
+    featuredImage,
+    ${richTextWithLinks},
+    categories,
+    tags,
+    author,
+    publishedAt,
+    metadata,
+    _updatedAt
+  }
+`;
+
+export const allArticlesQuery = groq`
+  *[_type == "article"] | order(publishedAt desc) {
+    _id,
+    title,
+    slug,
+    excerpt,
+    featuredImage,
+    categories,
+    tags,
+    author,
+    publishedAt,
+    metadata,
+    _updatedAt
+  }
+`;
+
+export const articleByIdQuery = groq`
+  *[_type == "article" && _id == $id][0] {
+    _id,
+    title,
+    slug,
+    excerpt,
+    featuredImage,
+    ${richTextWithLinks},
+    categories,
+    tags,
+    author,
+    publishedAt,
+    metadata,
+    _updatedAt
+  }
+`;

package/integrations/sanity/lib/integrations/sanity/sanity.cli.ts

@@ -0,0 +1,20 @@
+/**
+ * This configuration file lets you run `$ sanity [command]` in this folder
+ * Go to https://www.sanity.io/docs/cli to learn more.
+ **/
+import { defineCliConfig } from "sanity/cli";
+import { dataset, projectId } from "./env";
+
+export default defineCliConfig({
+	api: { projectId, dataset },
+	project: {
+		basePath: "/studio",
+	},
+	vite: {
+		resolve: {
+			alias: {
+				"~": __dirname,
+			},
+		},
+	},
+});

package/integrations/sanity/lib/integrations/sanity/sanity.config.ts

@@ -0,0 +1,94 @@
+/**
+ * This configuration is used to for the Sanity Studio that's mounted on the `/app/studio/[[...tool]]/page.tsx` route
+ */
+
+import { visionTool } from "@sanity/vision";
+import { defineConfig } from "sanity";
+import {
+	defineDocuments,
+	defineLocations,
+	presentationTool,
+} from "sanity/presentation";
+import { structureTool } from "sanity/structure";
+import { apiVersion, dataset, previewURL, projectId } from "./env";
+import { schema } from "./schemas";
+import { structure } from "./structure";
+
+// Helper function for URL resolution
+function resolveHref(documentType?: string, slug?: string): string | undefined {
+	switch (documentType) {
+		case "page":
+			return slug === "sanity" ? "/sanity" : `/sanity/${slug}`;
+		case "article":
+			return slug ? `/sanity/${slug}` : undefined;
+		default:
+			console.warn("Invalid document type:", documentType);
+			return undefined;
+	}
+}
+
+export default defineConfig({
+	basePath: "/studio",
+	projectId,
+	dataset,
+	schema,
+	plugins: [
+		// Presentation tool for visual editing
+		presentationTool({
+			resolve: {
+				// Map routes to documents and GROQ filters
+				mainDocuments: defineDocuments([
+					{
+						route: "/sanity",
+						filter: `_type == "page" && slug.current == "sanity"`,
+					},
+					{
+						route: "/sanity/:slug",
+						filter: `_type == "article" && slug.current == $slug && defined(slug.current)`,
+					},
+				]),
+				locations: {
+					page: defineLocations({
+						select: {
+							title: "title",
+							slug: "slug.current",
+						},
+						resolve: (doc) => ({
+							locations: [
+								{
+									title: doc?.title || "Untitled Page",
+									href: resolveHref("page", doc?.slug) ?? "",
+								},
+							],
+						}),
+					}),
+					article: defineLocations({
+						select: {
+							title: "title",
+							slug: "slug.current",
+						},
+						resolve: (doc) => ({
+							locations: [
+								{
+									title: doc?.title || "Untitled Article",
+									href: resolveHref("article", doc?.slug) ?? "",
+								},
+							],
+						}),
+					}),
+				},
+			},
+			previewUrl: {
+				origin: previewURL,
+				draftMode: {
+					enable: "/api/draft-mode/enable",
+					disable: "/api/draft-mode/disable",
+				},
+			},
+		}),
+		structureTool({ structure }),
+		// Vision is for querying with GROQ from inside the Studio
+		// https://www.sanity.io/docs/the-vision-plugin
+		visionTool({ defaultApiVersion: apiVersion }),
+	],
+});