# hydrogen-sanity
> [!TIP]
> **Upgrading from v4?** See the [migration guide](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/MIGRATE-v4-to-v5.md) for breaking changes and new features. 🎉
[Sanity.io](https://www.sanity.io) toolkit for [Hydrogen](https://hydrogen.shopify.dev/). Requires `@shopify/hydrogen >= 2025.5.0`.
Learn more about [getting started with Sanity](https://www.sanity.io/docs/getting-started).
**Features:**
- Drop-in preview mode handling with pre-built route and session management.
- Opinionated data fetching that automatically adapts to preview mode.
- Interactive live preview with automatic loader detection for [Visual Editing](https://www.sanity.io/docs/loaders-and-overlays) in Sanity's Presentation tool.
- Optimized image URL generation hooks with Sanity's image URL builder.
- TypeScript support with [Sanity TypeGen](https://www.sanity.io/docs/sanity-typegen).
> [!TIP]
>
> If you'd prefer a self-paced course on how to use Sanity and Hydrogen, check out the [Sanity and Shopify with Hydrogen on Sanity Learn](https://www.sanity.io/learn/course/sanity-and-shopify-with-hydrogen).
- [Installation](#installation)
- [Add Vite plugin](#add-vite-plugin)
- [Usage](#usage)
- [Satisfy TypeScript](#satisfy-typescript)
- [Set up the Sanity provider](#set-up-the-sanity-provider)
- [Interacting with Sanity data](#interacting-with-sanity-data)
- [Recommended: Using `query` and `Query` together](#recommended-using-query-and-query-together)
- [Alternative: Cached queries using `loadQuery`](#alternative-cached-queries-using-loadquery)
- [Additional `loadQuery` options](#additional-loadquery-options)
- [Alternative: Direct queries using `fetch`](#alternative-direct-queries-using-fetch)
- [Alternative: Using `client` directly](#alternative-using-client-directly)
- [Using Sanity TypeGen](#using-sanity-typegen)
- [Working with images](#working-with-images)
- [Enable preview mode](#enable-preview-mode)
- [Configure preview mode](#configure-preview-mode)
- [Add Visual Editing component](#add-visual-editing-component)
- [Visual Editing configuration options](#visual-editing-configuration-options)
- [Visual Editing components](#visual-editing-components)
- [Preview mode route](#preview-mode-route)
- [Set up CORS for front-end domains](#set-up-cors-for-front-end-domains)
- [Modify storefront's Content Security Policy (CSP)](#modify-storefronts-content-security-policy-csp)
- [Set up Presentation tool](#set-up-presentation-tool)
- [Troubleshooting](#troubleshooting)
- [Using `@sanity/client` directly](#using-sanityclient-directly)
- [Migration Guides](#migration-guides)
- [License](#license)
- [Develop & test](#develop--test)
- [Release new version](#release-new-version)
> [!NOTE]
> This package builds on [`@sanity/react-loader`](https://github.com/sanity-io/visual-editing/tree/main/packages/react-loader) and [`@sanity/visual-editing`](https://github.com/sanity-io/visual-editing/tree/main/packages/visual-editing), providing Hydrogen-specific optimizations and caching integration. For non-Hydrogen React applications, consider using these packages directly.
>
> Using this package isn't required for working with Sanity in a Hydrogen storefront. If you'd prefer to use `@sanity/react-loader` and/or `@sanity/client` directly, see [Using `@sanity/client` directly](#using-sanityclient-directly) below.
## Installation
```sh
npm install hydrogen-sanity @sanity/client
```
```sh
yarn add hydrogen-sanity @sanity/client
```
```sh
pnpm install hydrogen-sanity @sanity/client
```
### Add Vite plugin
Add the Vite plugin to your `vite.config.ts`:
```ts
import {defineConfig} from 'vite'
import {hydrogen} from '@shopify/hydrogen/vite'
import {sanity} from 'hydrogen-sanity/vite'
export default defineConfig({
plugins: [hydrogen(), sanity() /** ... */],
// ... other config
})
```
## Usage
Create the Sanity context and pass it through to your application, and optionally, configure the preview mode if you plan to setup Visual Editing
> [!NOTE]
> The examples below are up-to-date as of `npm create @shopify/hydrogen@2025.7.0`
```diff
// ./lib/context.ts
// ...all other imports
+ import {createSanityContext, type SanityContext} from 'hydrogen-sanity'
// Define the additional context object
const additionalContext = {
// Additional context for custom properties, CMS clients, 3P SDKs, etc.
// These will be available as both context.propertyName and context.get(propertyContext)
// Example of complex objects that could be added:
// cms: await createCMSClient(env),
// reviews: await createReviewsClient(env),
} as const;
// Automatically augment HydrogenAdditionalContext with the additional context type
type AdditionalContextType = typeof additionalContext;
declare global {
interface HydrogenAdditionalContext extends AdditionalContextType {
+
+ // Augment `HydrogenAdditionalContext` with the Sanity context
+ sanity: SanityContext;
}
}
export async function createHydrogenRouterContext(
request: Request,
env: Env,
executionContext: ExecutionContext,
) {
// ... Leave all other functions as-is
const waitUntil = executionContext.waitUntil.bind(executionContext)
const [cache, session] = await Promise.all([
caches.open('hydrogen'),
AppSession.init(request, [env.SESSION_SECRET]),
])
+ // Initialize the Sanity context
+ const sanity = await createSanityContext({
+ request,
+
+ // To use the Hydrogen cache for queries
+ cache,
+ waitUntil,
+
+ // Sanity client configuration
+ client: {
+ projectId: env.SANITY_PROJECT_ID,
+ dataset: env.SANITY_DATASET || 'production',
+ apiVersion: env.SANITY_API_VERSION || 'v2024-08-08',
+ useCdn: process.env.NODE_ENV === 'production',
+ },
+
+ // You can also initialize a client and pass it instead
+ // client: createClient({
+ // projectId: env.SANITY_PROJECT_ID,
+ // dataset: env.SANITY_DATASET,
+ // apiVersion: env.SANITY_API_VERSION,
+ // useCdn: process.env.NODE_ENV === 'production',
+ // }),
+
+ // Optionally, set a default cache strategy, defaults to `CacheLong`
+ // strategy: CacheShort() | null,
+ })
+ // Make `sanity` available to loaders and actions in the request context
const hydrogenContext = createHydrogenContext(
{
env,
request,
cache,
waitUntil,
session,
i18n: {language: 'EN', country: 'US'},
cart: {
queryFragment: CART_QUERY_FRAGMENT,
},
},
+ {
+ ...additionalContext
+ sanity,
+ } as const,
+ )
+
return hydrogenContext
}
```
Learn more about [Sanity's JavaScript client configuration](https://www.sanity.io/docs/js-client).
Update your environment variables with settings from your Sanity project.
- Copy these from [sanity.io/manage](https://sanity.io/manage).
- Or run `npx sanity@latest init --env` to fill the minimum required values from a new or existing project.
```sh
# Project ID
SANITY_PROJECT_ID=""
# Dataset name
SANITY_DATASET=""
# (Optional) Sanity API version
SANITY_API_VERSION=""
# Sanity token to authenticate requests in "preview" mode
# must have `viewer` role or higher access
# Create in sanity.io/manage
SANITY_PREVIEW_TOKEN=""
```
### Satisfy TypeScript
Update the environment variables in `Env` to include the ones you created above:
> [!NOTE]
> If you plan to reference any environment variables in the client bundle, say for your embedded Studio configuration, you must prefix them with either `PUBLIC_` or `SANITY_STUDIO_`
```diff
// ./env.d.ts
declare global {
// ...other types
interface Env extends HydrogenEnv {
// ...other environment variables
+ SANITY_PROJECT_ID: string
+ SANITY_DATASET?: string
+ SANITY_API_VERSION?: string
+ SANITY_PREVIEW_TOKEN: string
}
}
```
### Set up the Sanity provider
You now need to wrap your app with the Sanity provider to make Sanity context available to client-side hooks and components like `useImageUrl` and `Query`.
**Update entry.server.tsx**
Wrap your app with the Sanity provider in your server entry point:
```diff
// ./app/entry.server.tsx
export default async function handleRequest(
request: Request,
responseStatusCode: number,
responseHeaders: Headers,
reactRouterContext: EntryContext,
- context: AppLoadContext,
+ context: HydrogenRouterContextProvider,
) {
+ const {SanityProvider} = context.sanity
// ... CSP setup etc ...
const body = await renderToReadableStream(
+
+ ,
// ... render options
)
}
```
**Update root.tsx**
Add the `Sanity` component to your root layout:
```diff
// ./app/root.tsx
+ import {Sanity} from 'hydrogen-sanity'
export function Layout({children}: {children?: React.ReactNode}) {
const nonce = useNonce()
return (
{children}
+ {/* Add Sanity client-side script */}
+
)
}
```
## Interacting with Sanity data
### Recommended: Using `query` and `Query` together
The `query` method and `Query` component work together to provide an optimized data fetching and rendering experience that automatically adapts based on whether Sanity preview mode is active:
**Best for**: Most applications wanting opinionated best practices with automatic optimization
- **Opinionated approach**: Curated patterns that codify Hydrogen + Sanity best practices
- Automatic preview mode detection and switching
- Built-in Visual Editing with click-to-edit overlays
- **Bundle optimization**: Preview-related code is conditionally loaded only when needed
- **Configuration decisions made for you**: Cache strategies, session management, and Visual Editing setup follow recommended approaches
**How it works**:
- **When preview mode is active**: Dynamically imports `@sanity/react-loader` with `loadQuery` for loader integration and client-side re-rendering with `useQuery` for real-time Studio updates
- **When preview mode is inactive**: Uses lightweight direct client `fetch` for optimal performance with static rendering
- **Bundle efficiency**: The `Query` component uses React's `lazy()` to conditionally load client-side preview components only when needed, while server-side `loadQuery` imports happen at runtime only when preview mode is detected
**Step 1: Fetch data in your loader with `query`**
```ts
import {defineQuery} from 'groq'
const HOMEPAGE_QUERY = defineQuery(`*[_id == "home"][0]{
_id,
title,
hero {
title,
description,
image {
asset->{
_id,
url
},
alt
}
},
modules[] {
_type,
_type == "productShowcase" => {
products[]-> {
_id,
store {
title,
slug,
previewImageUrl
}
}
}
}
}`)
export async function loader({context}: LoaderFunctionArgs) {
const initial = await context.sanity.query(HOMEPAGE_QUERY, undefined, {
tag: 'homepage',
hydrogen: {debug: {displayName: 'query Homepage'}},
})
return {initial}
}
```
**Step 2: Render with the `Query` component**
```tsx
import {Query} from 'hydrogen-sanity'
export default function HomePage({loaderData}: {loaderData: {initial: any}}) {
const {initial} = loaderData
return (
{(homepage, encodeDataAttribute) => (
{homepage?.hero?.title}
{homepage?.hero?.description}
{homepage?.modules?.map((module) => {
switch (module._type) {
case 'productShowcase':
return (
{module.products?.map((product) => (
{product.store?.title}
{product.store?.slug && (
View Product
)}
))}
)
default:
return null
}
})}
)}
)
}
```
> [!NOTE]
> The `encodeDataAttribute` function enables click-to-edit functionality in Sanity Studio's Presentation tool. It's only available when Sanity preview mode is active (managed via preview session) and returns `undefined` otherwise.
**Advanced Options**
Both methods accept the same options as their underlying implementations:
```ts
// In your loader
const page = await context.sanity.query(queryString, params, {
// Hydrogen caching options
hydrogen: {
cache: CacheShort(),
debug: {displayName: 'query Homepage'},
},
// Sanity request options
tag: 'home',
})
// In your component
Loading...} // React Suspense props
>
{(data) => }
```
### Alternative: Cached queries using `loadQuery`
**Best for**: Full control over preview mode behavior and loader integration (alternative to `query`/`Query`)
- Manual loader integration with real-time Studio updates when preview mode is active
- Uses `useQuery` hooks for client-side re-rendering with Sanity Studio
Query Sanity's API and use Hydrogen's cache to store the response (defaults to `CacheLong` caching strategy). When Sanity preview mode is active, `loadQuery` automatically bypasses the cache.
Learn more about configuring [caching in Hydrogen](https://shopify.dev/docs/custom-storefronts/hydrogen/caching).
Sanity queries appear in Hydrogen's [Subrequest Profiler](https://shopify.dev/docs/custom-storefronts/hydrogen/debugging/subrequest-profiler). By default, they're titled `Sanity query`. You can give your queries more descriptive titles by using the request option below.
```ts
export async function loader({context, params}: LoaderFunctionArgs) {
const query = `*[_type == "page" && _id == $id][0]`
const params = {id: 'home'}
const initial = await context.sanity.loadQuery(query, params)
return {initial}
}
```
#### Additional `loadQuery` options
If you need to pass any additional options to the request provide `queryOptions` like so:
```ts
const page = await context.sanity.loadQuery(query, params, {
// Optionally customize the cache strategy for this request
hydrogen: {
cache: CacheShort(),
// Or disable caching for this request
// cache: CacheNone(),
// If you'd like to add a custom display title that will
// display in the Subrequest Profiler, you can pass that here:
// debug: {
// displayName: 'query Homepage'
// },
// You can also pass a function do determine whether or not to cache the response
// shouldCacheResult(value){
// return true
// },
},
// ...as well as other request options
// tag: 'home',
// headers: {
// 'Accept-Encoding': 'br, gzip, *',
// },
})
```
> [!TIP]
> Learn more about [request tagging](https://www.sanity.io/docs/reference-api-request-tags).
### Alternative: Direct queries using `fetch`
**Best for**: When preview mode is not needed and bundle optimization is priority
- Lightweight with direct client results
- No preview or loader integration
For Sanity queries that don't need loader integration, there is a `fetch` method that also integrates with Hydrogen's cache:
```ts
export async function loader({context, params}: LoaderFunctionArgs) {
const query = `*[_type == "page" && _id == $id][0]`
const params = {id: 'home'}
const page = await context.sanity.fetch(query, params, {
hydrogen: {
cache: CacheShort(),
debug: {displayName: 'fetch Homepage'},
},
tag: 'home',
})
return {page}
}
```
### Alternative: Using `client` directly
The Sanity client (either instantiated from your configuration or passed through directly) is also available in your app's context. It is recommended to use `query` for data fetching; but the Sanity client can be used for mutations within actions, for example:
```ts
export async function action({context, request}: ActionFunctionArgs) {
if (!isAuthenticated(request)) {
return redirect('/login')
}
return context.sanity
.withConfig({
token: context.env.SANITY_WRITE_TOKEN,
})
.client.create({
_type: 'comment',
text: request.body.get('text'),
})
}
```
### Using Sanity TypeGen
[Sanity TypeGen](https://www.sanity.io/docs/sanity-typegen) generates TypeScript definitions for your [GROQ](https://www.sanity.io/docs/groq) queries. To use TypeGen with `hydrogen-sanity`, install `groq` as a dependency:
```sh
npm install groq
```
> [!TIP]
> Refer to TypeGen steps covered in the [Sanity TypeGen documentation](https://www.sanity.io/docs/sanity-typegen). TypeGen with `overloadClientMethods: true` uses [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html) to automatically generate types for your GROQ queries.
Now your queries will have automatic type inference:
```ts
import {defineQuery} from 'groq'
const HOMEPAGE_QUERY = defineQuery(`*[_id == "home"][0]`)
export async function loader({context, params}: LoaderFunctionArgs) {
const params = {id: 'home'}
const initial = await context.sanity.loadQuery(HOMEPAGE_QUERY, params)
return {initial}
}
```
## Working with images
The `useImageUrl` hook provides a convenient way to generate optimized image URLs from Sanity image assets with the [image URL builder](https://www.sanity.io/docs/image-url).
```tsx
import {useImageUrl} from 'hydrogen-sanity'
function HeroBanner({hero}: {hero: {image: SanityImageSource}}) {
const imageUrl = useImageUrl(hero.image)
return (