bsmnt 0.0.0

package/docs/sanity-setup-steps.md

@@ -0,0 +1,199 @@
+# Sanity Project Setup — Automated Steps
+
+> Reproducible steps for programmatically creating a Sanity project, dataset, API token, and `.env.local` configuration. No browser or interactive prompts required.
+
+---
+
+## Prerequisites
+
+- `@sanity/cli` available via `npx` (comes with `sanity` package)
+- User must be logged in to Sanity CLI (`npx sanity login`)
+- Project already has `next-sanity`, `@sanity/client`, `sanity` installed
+
+---
+
+## Step 1: Verify Sanity CLI is available
+
+```bash
+npx sanity --version
+```
+
+If this fails, the sanity packages aren't installed. Run:
+
+```bash
+bun add next-sanity @sanity/client @sanity/image-url sanity @sanity/vision
+```
+
+---
+
+## Step 2: Verify user is authenticated
+
+```bash
+npx sanity projects list
+```
+
+- If this returns a list of projects, the user is logged in.
+- If it fails with an auth error, the user needs to run `npx sanity login` first (this is interactive and opens a browser — cannot be automated).
+
+---
+
+## Step 3: Create the Sanity project
+
+```bash
+npx sanity projects create --name "<project-name>" --dataset production
+```
+
+**Output to parse:**
+
+```
+Project created successfully!
+ID: <project-id>
+Name: <project-name>
+Organization: <org>
+Dataset: production (public)
+```
+
+**Extract the project ID** from the output. It's the alphanumeric string after `ID: ` (e.g., `1poovu2i`).
+
+---
+
+## Step 4: Get the user's auth token
+
+The Sanity CLI stores the user's session token locally. Retrieve it with:
+
+```bash
+npx sanity debug --secrets 2>&1 | grep "Auth token"
+```
+
+**Output:**
+
+```
+  Auth token: '<token-string>'
+```
+
+**Parse the token** from between the single quotes. Note: the output includes ANSI color codes (`[32m` and `[39m`) that need to be stripped.
+
+---
+
+## Step 5: Create an API read token
+
+Use the Sanity HTTP API to create a viewer token for the project:
+
+```bash
+curl -s -X POST "https://api.sanity.io/v2021-06-07/projects/<project-id>/tokens" \
+  -H "Authorization: Bearer <auth-token-from-step-4>" \
+  -H "Content-Type: application/json" \
+  -d '{"label": "Next.js Read Token", "roleName": "viewer"}'
+```
+
+**Response:**
+
+```json
+{
+  "id": "si8WgRxQuts4CN",
+  "key": "<the-api-read-token>",
+  "roles": [{ "name": "viewer", "title": "Viewer" }],
+  "label": "Next.js Read Token"
+}
+```
+
+**Extract the `key` field** — this is the `SANITY_API_READ_TOKEN`.
+
+---
+
+## Step 6: Write `.env.local`
+
+Create `.env.local` in the project root with:
+
+```env
+# Sanity CMS
+NEXT_PUBLIC_SANITY_PROJECT_ID=<project-id>
+NEXT_PUBLIC_SANITY_DATASET=production
+SANITY_API_READ_TOKEN=<api-read-token>
+NEXT_PUBLIC_SANITY_API_READ_TOKEN=<api-read-token>
+```
+
+**Why both `SANITY_API_READ_TOKEN` and `NEXT_PUBLIC_SANITY_API_READ_TOKEN`?**
+
+The next-starter template's `env.ts` reads from `NEXT_PUBLIC_SANITY_API_READ_TOKEN` (exposed to client for draft mode / visual editing). `SANITY_API_READ_TOKEN` is the conventional server-only name. Setting both ensures compatibility regardless of which convention the project follows.
+
+---
+
+## Step 7: Verify the connection
+
+Test that the token and project ID work by querying the API:
+
+```bash
+curl -s "https://<project-id>.api.sanity.io/v2024-03-15/data/query/production?query=*%5B0%5D" \
+  -H "Authorization: Bearer <api-read-token>"
+```
+
+**Success response:**
+
+```json
+{
+  "query": "*[0]",
+  "result": { ... },
+  "ms": 2
+}
+```
+
+If the response contains `"result"` (even if it's `null` for an empty dataset), the setup is correct.
+
+---
+
+## Step 8: Ensure `.env.local` is gitignored
+
+Check if `.gitignore` exists and includes `.env.local`. If not, add it:
+
+```bash
+# Check
+grep -q ".env.local" .gitignore 2>/dev/null
+
+# If missing or .gitignore doesn't exist, ensure it's added
+echo ".env.local" >> .gitignore
+```
+
+---
+
+## Summary of values produced
+
+| Variable | Source |
+|----------|--------|
+| `NEXT_PUBLIC_SANITY_PROJECT_ID` | Step 3 — `ID` field from project creation output |
+| `NEXT_PUBLIC_SANITY_DATASET` | Hardcoded to `production` (passed in Step 3) |
+| `SANITY_API_READ_TOKEN` | Step 5 — `key` field from token creation response |
+| `NEXT_PUBLIC_SANITY_API_READ_TOKEN` | Same as above |
+
+---
+
+## Error handling notes
+
+| Step | Possible failure | How to handle |
+|------|-----------------|---------------|
+| 2 | Not logged in | Prompt user to run `npx sanity login` — requires browser |
+| 3 | Org selection needed | Add `--organization <org-id>` flag if user has multiple orgs |
+| 4 | Token not found | Auth token location varies by OS. Fallback: read `~/.config/sanity/config.json` |
+| 5 | 401/403 from API | Auth token expired or invalid — user needs to `npx sanity login` again |
+| 5 | 400 bad request | Check project ID is correct, check auth header format |
+| 7 | Connection refused | Project ID or dataset name is wrong |
+
+---
+
+## CLI integration notes
+
+For a `basement init` command, the flow would be:
+
+```
+1. Check: `npx sanity projects list` → confirms auth
+2. Prompt: "Project name?" (default: directory name)
+3. Run: `npx sanity projects create --name <name> --dataset production`
+4. Parse: project ID from stdout
+5. Get: auth token from `npx sanity debug --secrets`
+6. Create: API token via HTTP POST
+7. Write: `.env.local` with all four variables
+8. Verify: curl test query
+9. Print: "Sanity Studio available at /studio"
+```
+
+No interactive Sanity prompts needed. The only prerequisite is that `npx sanity login` has been run at least once.

package/integrations/basehub/README.md

@@ -0,0 +1,3 @@
+# BaseHub Integration
+
+Coming soon...

package/integrations/sanity/app/api/draft-mode/disable/route.ts

@@ -0,0 +1,7 @@
+import { draftMode } from "next/headers";
+import { type NextRequest, NextResponse } from "next/server";
+
+export async function GET(request: NextRequest) {
+	(await draftMode()).disable();
+	return NextResponse.redirect(new URL("/", request.url));
+}

package/integrations/sanity/app/api/draft-mode/enable/route.ts

@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { defineEnableDraftMode } from "next-sanity/draft-mode";
+import { isSanityConfigured } from "@/lib/integrations/check-integration";
+import { client } from "@/lib/integrations/sanity/client";
+import { privateToken } from "@/lib/integrations/sanity/env";
+
+// Only enable draft mode if Sanity is configured
+const draftModeHandler =
+	isSanityConfigured() && client
+		? defineEnableDraftMode({
+				client: client.withConfig({ token: privateToken }),
+			})
+		: {
+				GET: () =>
+					NextResponse.json(
+						{ error: "Sanity is not configured" },
+						{ status: 503 },
+					),
+			};
+
+export const { GET } = draftModeHandler;

package/integrations/sanity/app/api/revalidate/route.ts

@@ -0,0 +1,37 @@
+import { revalidateTag } from "next/cache";
+import { type NextRequest, NextResponse } from "next/server";
+import { parseBody } from "next-sanity/webhook";
+
+export async function POST(request: NextRequest) {
+	try {
+		const { body, isValidSignature } = await parseBody<{
+			_type: string;
+			slug?: { current: string };
+		}>(request, process.env.SANITY_REVALIDATE_SECRET);
+
+		if (!isValidSignature) {
+			return new Response("Invalid signature", { status: 401 });
+		}
+
+		if (!body?._type) {
+			return new Response("Bad Request", { status: 400 });
+		}
+
+		// Revalidate the specific document type
+		revalidateTag(body._type);
+
+		// If there's a slug, revalidate the specific page
+		if (body.slug?.current) {
+			revalidateTag(`${body._type}:${body.slug.current}`);
+		}
+
+		return NextResponse.json({
+			status: 200,
+			revalidated: true,
+			now: Date.now(),
+		});
+	} catch (error) {
+		console.error("Revalidation error:", error);
+		return new Response("Internal Server Error", { status: 500 });
+	}
+}

package/integrations/sanity/app/layout.tsx

@@ -0,0 +1,111 @@
+import type { Metadata, Viewport } from "next";
+import { Geist } from "next/font/google";
+import { type PropsWithChildren, Suspense } from "react";
+import { SanityStudioGuard } from "@/components/sanity/studio-guard";
+import { SanityVisualEditing } from "@/components/sanity/visual-editing";
+import { Link } from "@/components/ui/link";
+import { themes } from "@/lib/styles/colors";
+import { fontsVariable } from "@/lib/styles/fonts";
+import AppData from "@/package.json";
+import "@/lib/styles/css/index.css";
+import { cn } from "@/lib/styles/cn";
+
+const APP_NAME = AppData.name;
+const APP_DEFAULT_TITLE = "Basement Starter";
+const APP_TITLE_TEMPLATE = "%s - Basement Starter";
+const APP_DESCRIPTION = AppData.description;
+const APP_BASE_URL =
+	process.env.NEXT_PUBLIC_BASE_URL ?? "https://localhost:3000";
+
+const geist = Geist({
+	subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+	alternates: {
+		canonical: "/",
+		languages: {
+			"en-US": "/en-US",
+		},
+	},
+	appleWebApp: {
+		capable: true,
+		statusBarStyle: "default",
+		title: APP_DEFAULT_TITLE,
+	},
+	applicationName: APP_NAME,
+	authors: [{ name: "basement.studio", url: "https://basement.studio" }],
+	description: APP_DESCRIPTION,
+	formatDetection: { telephone: false },
+	metadataBase: new URL(APP_BASE_URL),
+	openGraph: {
+		description: APP_DESCRIPTION,
+		images: [
+			{
+				alt: APP_DEFAULT_TITLE,
+				height: 630,
+				url: "/opengraph-image.jpg",
+				width: 1200,
+			},
+		],
+		locale: "en_US",
+		siteName: APP_NAME,
+		title: {
+			default: APP_DEFAULT_TITLE,
+			template: APP_TITLE_TEMPLATE,
+		},
+		type: "website",
+		url: APP_BASE_URL,
+	},
+	other: {
+		"fb:app_id": process.env.NEXT_PUBLIC_FACEBOOK_APP_ID || "",
+	},
+	title: {
+		default: APP_DEFAULT_TITLE,
+		template: APP_TITLE_TEMPLATE,
+	},
+	twitter: {
+		card: "summary_large_image",
+		description: APP_DESCRIPTION,
+		title: {
+			default: APP_DEFAULT_TITLE,
+			template: APP_TITLE_TEMPLATE,
+		},
+	},
+};
+
+export const viewport: Viewport = {
+	colorScheme: "normal",
+	themeColor: themes.dark.primary,
+};
+
+export default function Layout({ children }: PropsWithChildren) {
+	return (
+		<html
+			lang="en"
+			dir="ltr"
+			className={cn(fontsVariable, geist.className)}
+			suppressHydrationWarning
+		>
+			<body>
+				<Suspense fallback={null}>
+					<SanityStudioGuard>
+						{/* Skip link for keyboard navigation accessibility */}
+						<Suspense fallback={null}>
+							<Link
+								href="#main-content"
+								className="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-9999 focus:rounded focus:bg-black focus:px-4 focus:py-2 focus:text-white focus:outline-none focus:ring-2 focus:ring-white"
+							>
+								Skip to main content
+							</Link>
+						</Suspense>
+					</SanityStudioGuard>
+				</Suspense>
+
+				{children}
+
+				<SanityVisualEditing />
+			</body>
+		</html>
+	);
+}

package/integrations/sanity/app/sitemap.ts

@@ -0,0 +1,80 @@
+import type { MetadataRoute } from "next";
+import { isSanityConfigured } from "@/lib/integrations/check-integration";
+
+const APP_BASE_URL =
+	process.env.NEXT_PUBLIC_BASE_URL ?? "https://localhost:3000";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+	const baseRoutes: MetadataRoute.Sitemap = [
+		{
+			url: APP_BASE_URL,
+			lastModified: new Date(),
+			changeFrequency: "daily",
+			priority: 1,
+		},
+	];
+
+	// Only fetch Sanity pages if Sanity is configured
+	if (isSanityConfigured()) {
+		try {
+			const sanityModule = await import("@/lib/integrations/sanity/client");
+			const sanityGroq = await import("next-sanity");
+
+			const client = sanityModule?.client;
+			const groq = sanityGroq?.groq;
+
+			// Skip if client is null (shouldn't happen since we check isSanityConfigured)
+			if (!(client && groq)) return baseRoutes;
+
+			type SanityDocument = {
+				slug: { current: string };
+				_updatedAt: string;
+				metadata?: { noIndex?: boolean };
+			};
+
+			// Fetch all published pages and articles
+			const pages = (await client.fetch(
+				groq`*[_type == "page" && defined(slug.current)] {
+          slug,
+          _updatedAt,
+          metadata
+        }`,
+			)) as SanityDocument[];
+
+			const articles = (await client.fetch(
+				groq`*[_type == "article" && defined(slug.current)] {
+          slug,
+          _updatedAt,
+          metadata
+        }`,
+			)) as SanityDocument[];
+
+			// Add pages to sitemap (exclude noIndex pages)
+			const pageEntries: MetadataRoute.Sitemap = pages
+				.filter((page: SanityDocument) => !page.metadata?.noIndex)
+				.map((page: SanityDocument) => ({
+					url: `${APP_BASE_URL}/${page.slug.current}`,
+					lastModified: new Date(page._updatedAt),
+					changeFrequency: "weekly" as const,
+					priority: 0.8,
+				}));
+
+			// Add articles to sitemap (exclude noIndex articles)
+			const articleEntries: MetadataRoute.Sitemap = articles
+				.filter((article: SanityDocument) => !article.metadata?.noIndex)
+				.map((article: SanityDocument) => ({
+					url: `${APP_BASE_URL}/blog/${article.slug.current}`,
+					lastModified: new Date(article._updatedAt),
+					changeFrequency: "weekly" as const,
+					priority: 0.7,
+				}));
+
+			return [...baseRoutes, ...pageEntries, ...articleEntries];
+		} catch (error) {
+			console.error("Error generating sitemap from Sanity:", error);
+			return baseRoutes;
+		}
+	}
+
+	return baseRoutes;
+}

package/integrations/sanity/app/studio/[[...tool]]/page.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { NextStudio } from "next-sanity/studio";
+import config from "@/lib/integrations/sanity/sanity.config";
+
+export default function StudioPage() {
+	return <NextStudio config={config} />;
+}

package/integrations/sanity/app/studio/layout.tsx

@@ -0,0 +1,7 @@
+export default function StudioLayout({
+	children,
+}: {
+	children: React.ReactNode;
+}) {
+	return children;
+}

package/integrations/sanity/components/ui/sanity-image/index.tsx

@@ -0,0 +1,37 @@
+import { getImageDimensions } from "@sanity/asset-utils";
+import { Image, type ImageProps } from "@/components/ui/image";
+import { urlForImage } from "@/lib/integrations/sanity/utils/image";
+
+interface SanityImageProps extends Omit<ImageProps, "src" | "aspectRatio"> {
+	image: {
+		asset: {
+			_ref: string;
+			_type: "reference";
+		};
+		alt?: string;
+		hotspot?: object;
+		crop?: object;
+	};
+	maxWidth?: number;
+}
+
+export function SanityImage({
+	image,
+	maxWidth = 1920,
+	alt,
+	...props
+}: SanityImageProps) {
+	if (!image?.asset) return null;
+
+	const { width, height } = getImageDimensions(image.asset);
+	const aspectRatio = width / height;
+
+	return (
+		<Image
+			src={urlForImage(image).width(maxWidth).url()}
+			alt={alt || image.alt || ""}
+			aspectRatio={aspectRatio}
+			{...props}
+		/>
+	);
+}

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

@@ -0,0 +1,58 @@
+# Integrations
+
+Third-party service integrations. All are optional—remove unused ones with `bun run setup:project`.
+
+## Available Integrations
+
+| Integration | Purpose | Documentation |
+|-------------|---------|---------------|
+| [Sanity](sanity/README.md) | Headless CMS | Visual editing, content management |
+| [Shopify](shopify/README.md) | E-commerce | Cart, products, checkout |
+
+## Environment Variables
+
+```env
+# Sanity CMS
+NEXT_PUBLIC_SANITY_PROJECT_ID="your-project-id"
+NEXT_PUBLIC_SANITY_DATASET="production"
+NEXT_PUBLIC_SANITY_STUDIO_URL="http://localhost:3000/studio"
+SANITY_API_WRITE_TOKEN="your-write-token"
+
+# Shopify
+SHOPIFY_STORE_DOMAIN="your-store.myshopify.com"
+SHOPIFY_STOREFRONT_ACCESS_TOKEN="your-token"
+SHOPIFY_REVALIDATION_SECRET="your-secret"
+
+# Analytics
+NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID=GTM-XXXXXX
+NEXT_PUBLIC_GOOGLE_ANALYTICS=G-XXXXXXXXXX
+```
+
+## Quick Usage
+
+```tsx
+// Sanity
+import { sanityFetch } from '@/integrations/sanity/live'
+import { RichText } from '@/integrations/sanity/components/rich-text'
+const { data } = await sanityFetch({ query: pageQuery })
+
+// Shopify
+import { Cart, AddToCart } from '@/lib/integrations/shopify/cart'
+<Cart><AddToCart product={product} /></Cart>
+
+```
+
+## Removing Integrations
+
+Run `bun run setup:project` for interactive removal, or manually:
+
+```bash
+# Sanity (~150-200KB savings)
+rm -rf lib/integrations/sanity app/studio app/(examples)/sanity
+bun remove @sanity/asset-utils @sanity/image-url next-sanity sanity
+
+# Shopify (~50-80KB)
+rm -rf lib/integrations/shopify app/(examples)/shopify
+```
+
+After removal: `bun lint:fix && bun build`

package/integrations/sanity/lib/integrations/check-integration.ts

@@ -0,0 +1,62 @@
+/**
+ * Integration Configuration Checker
+ *
+ * Utilities to check if integrations are configured via environment variables.
+ * This helps with tree-shaking unused integrations from the bundle.
+ *
+ * Usage:
+ * ```ts
+ * import { isSanityConfigured } from '@/integrations/check-integration'
+ *
+ * if (isSanityConfigured()) {
+ *   // Only import and use Sanity code if configured
+ *   const { sanityFetch } = await import('next-sanity/live')
+ * }
+ * ```
+ */
+
+/**
+ * Check if Sanity CMS is configured
+ * Requires: NEXT_PUBLIC_SANITY_PROJECT_ID and NEXT_PUBLIC_SANITY_DATASET
+ */
+export function isSanityConfigured(): boolean {
+	return Boolean(
+		process.env.NEXT_PUBLIC_SANITY_PROJECT_ID &&
+			process.env.NEXT_PUBLIC_SANITY_DATASET,
+	);
+}
+
+/**
+ * Check if Google Analytics is configured
+ * Requires: NEXT_PUBLIC_GOOGLE_ANALYTICS or NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID
+ */
+export function isAnalyticsConfigured(): boolean {
+	return Boolean(
+		process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS ||
+			process.env.NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID,
+	);
+}
+
+/**
+ * Get a list of all configured integrations
+ */
+export function getConfiguredIntegrations(): string[] {
+	const integrations: string[] = [];
+
+	if (isSanityConfigured()) integrations.push("Sanity");
+	if (isAnalyticsConfigured()) integrations.push("Analytics");
+
+	return integrations;
+}
+
+/**
+ * Get a list of all unconfigured integrations
+ */
+export function getUnconfiguredIntegrations(): string[] {
+	const integrations: string[] = [];
+
+	if (!isSanityConfigured()) integrations.push("Sanity");
+	if (!isAnalyticsConfigured()) integrations.push("Analytics");
+
+	return integrations;
+}