Sanity Client Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Sanity Client Configuration serves as the foundational bridge between the Next.js frontend and the Sanity Content Lake. It centralizes environment variables, API versioning, and client instantiation to ensure consistent data fetching across the application. This configuration supports multiple operational modes, including standard production fetching, real-time "live" content updates, and draft mode for visual editing.
By utilizing the next-sanity library, the project implements a pre-configured client that handles Content Source Maps (stega) for visual editing and utilizes a Content Delivery Network (CDN) for optimized performance in production.
Sources: sanity/lib/client.ts, sanity/lib/api.ts, README.md:10-15
Core API Configuration
The API configuration resides in a lean module designed to be reused across both client-side and server-side functions without unnecessarily increasing bundle sizes. It primarily manages the extraction and validation of environment variables required to authenticate and locate the Sanity project.
Environment Variables and Constants
The system uses an assertValue helper function to ensure that critical configuration strings are present at runtime, throwing an explicit error if they are missing.
| Variable | Source | Description |
|---|---|---|
projectId | NEXT_PUBLIC_SANITY_PROJECT_ID | The unique identifier for the Sanity project. |
dataset | NEXT_PUBLIC_SANITY_DATASET | The specific dataset (e.g., 'production') to query. |
apiVersion | NEXT_PUBLIC_SANITY_API_VERSION | The API version string, defaulting to '2025-02-27'. |
studioUrl | Hardcoded: /studio | The base path where the Sanity Studio is mounted. |
Sources: sanity/lib/api.ts:7-34
Client Architecture and Initialization
The project initializes a primary client instance using createClient from next-sanity. This client is configured with specific behaviors for data perspective and visual editing.
Content Perspective and Stega
The client is configured with a published perspective by default, ensuring that only officially released content is visible to end-users. Furthermore, it implements "stega" (Content Source Maps), which embeds metadata into strings to enable the Presentation tool to identify which Sanity document and field produced a specific piece of text on the webpage.
The diagram above illustrates the flow of configuration from environment variables through the shared library modules to the final client features.
Sources: sanity/lib/client.ts:4-22, sanity/lib/api.ts:7-20
Live Redirection and Fetching
To facilitate real-time updates without manual page refreshes, the project utilizes defineLive. This creates a SanityLive component and a sanityFetch function that utilize both browser and server tokens for authenticated, real-time data streaming.
Sources: sanity/lib/live.ts:1-10
Studio and Draft Mode Configuration
The client configuration extends into the authoring environment (Sanity Studio) and the Draft Mode API routes.
Draft Mode Enabling
For previewing unpublished changes, the project provides a dedicated API route. This route uses a specialized version of the client that includes a write/read token to bypass the standard published perspective.
// app/api/draft-mode/enable/route.ts
export const {GET} = defineEnableDraftMode({
client: client.withConfig({token}),
})
Sources: app/api/draft-mode/enable/route.ts:1-7
Studio Configuration
The sanity.config.ts file utilizes the shared API constants to mount the Studio. It integrates various tools such as the presentationTool (for visual editing) and the visionTool (for GROQ querying).
| Component | Configuration File | Purpose |
|---|---|---|
projectId | sanity.config.ts | Identifies the target project for the Studio. |
presentationTool | sanity.config.ts | Enables side-by-side previewing with a resolve configuration. |
previewUrl | sanity.config.ts | Points to the /api/draft-mode/enable route for live previews. |
Sources: sanity.config.ts:21-65
Summary
The Sanity Client Configuration is a modular system that centralizes project identity and access logic. By separating core API constants (api.ts), the primary client instance (client.ts), and live fetching utilities (live.ts), the architecture ensures that the Next.js application remains performant while providing robust tools for content authors, including real-time previews and visual editing capabilities.