# sanity-io/hydrogen-sanity architecture

> Architecture diagram of the GitHub repository sanity-io/hydrogen-sanity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanity-io/hydrogen-sanity
- Repository: https://github.com/sanity-io/hydrogen-sanity

## Overview

Hydrogen Sanity connects a Hydrogen storefront to Sanity content: request context configures the client and cache, preview routes manage preview state, and queries provide server data or live client updates. Visual Editing adds overlays and Studio-driven refreshes. The companion Sanity Studio configuration supplies editorial schemas and Shopify-aware document tooling. README capabilities include image URL helpers, TypeGen support, and a Vite plugin. Some of these are represented by their exact source paths but were not sampled; edges are limited to documented or indexed relationships.

Main entry points: [`packages/hydrogen-sanity/src/context.ts`](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/context.ts) (Request context), [`packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx`](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx) (Editing overlays), [`packages/hydrogen-sanity/src/Query.client.tsx`](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/Query.client.tsx) (Client query), [`packages/hydrogen-sanity/src/visual-editing/VisualEditing.client.tsx`](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/VisualEditing.client.tsx) (Visual Editing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_storefront["Hydrogen runtime"]
  node_context["Request context<br/>[context.ts]"]
  node_provider["Sanity provider<br/>[provider.tsx]"]
  node_query["Query component<br/>[Query.tsx]"]
  node_clientquery["Client query<br/>[Query.client.tsx]"]
  node_image["Image URL helpers<br/>[image.ts]"]
  node_vite["Vite integration<br/>[plugin.ts]"]
end

subgraph group_preview["Preview and editing"]
  node_previewroute["Preview route<br/>[route.ts]"]
  node_previewsession["Preview session<br/>[session.ts]"]
  node_visual["Visual Editing"]
  node_live["Live mode"]
  node_overlays["Editing overlays"]
  node_queryregistry["Query registry<br/>[registry.tsx]"]
  node_history["History adapter<br/>[history.ts]"]
  node_refresh["Refresh handler<br/>[refresh.ts]"]
end

subgraph group_studio["Sanity Studio"]
  node_studioconfig["Studio configuration<br/>[sanity.config.ts]"]
  node_schemas["Content schemas"]
  node_structure["Studio structure"]
end

subgraph group_commerce["Shopify content"]
  node_shopifydocs["Shopify documents"]
  node_shopifytools["Shopify Studio tools"]
end

node_developer(("Storefront developer"))
node_sanityapi{{"Sanity API"}}
node_studio(("Sanity Studio"))
node_shopify{{"Shopify"}}

node_developer -->|"configures"| node_context
node_context -->|"creates client"| node_sanityapi
node_context -->|"provides context"| node_provider
node_context -->|"checks preview state"| node_previewsession
node_query -->|"loads live query"| node_clientquery
node_clientquery -->|"registers query"| node_queryregistry
node_clientquery -.->|"fetches updates"| node_sanityapi
node_developer -->|"renders content"| node_query
node_developer -->|"uses image helpers"| node_image
node_developer -->|"configures plugin"| node_vite
node_developer -->|"enables preview"| node_previewroute
node_previewroute -->|"commits session"| node_previewsession
node_studio -->|"validates preview URL"| node_previewroute
node_visual -->|"renders overlays"| node_overlays
node_visual -->|"enables live mode"| node_live
node_overlays -->|"uses history"| node_history
node_overlays -->|"uses refresh"| node_refresh
node_overlays -->|"checks loaders"| node_queryregistry
node_studio -->|"drives editing"| node_visual
node_studioconfig -->|"registers schemas"| node_schemas
node_studioconfig -.->|"configures navigation"| node_structure
node_schemas -->|"defines commerce types"| node_shopifydocs
node_shopifytools -.->|"links documents"| node_shopify

click node_context "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/context.ts"
click node_provider "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/provider.tsx"
click node_query "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/Query.tsx"
click node_clientquery "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/Query.client.tsx"
click node_image "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/image.ts"
click node_vite "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/vite/plugin.ts"
click node_previewroute "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/preview/route.ts"
click node_previewsession "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/preview/session.ts"
click node_visual "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/VisualEditing.client.tsx"
click node_live "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/LiveMode.client.tsx"
click node_overlays "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx"
click node_queryregistry "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/registry.tsx"
click node_history "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/hooks/history.ts"
click node_refresh "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/hooks/refresh.ts"
click node_studioconfig "https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/sanity-config/sanity.config.ts"
click node_schemas "https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/schemaTypes"
click node_structure "https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/structure"
click node_shopifydocs "https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/schemaTypes/objects/shopify"
click node_shopifytools "https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/plugins/customDocumentActions"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_context,node_provider,node_query,node_clientquery,node_image,node_vite toneBlue
class node_previewroute,node_previewsession,node_visual,node_live,node_overlays,node_queryregistry,node_history,node_refresh toneAmber
class node_studioconfig,node_schemas,node_structure,node_sanityapi toneMint
class node_shopifydocs,node_shopifytools toneRose
class node_developer,node_studio,node_shopify toneIndigo
```

## Components

### Hydrogen runtime

- [Request context](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/context.ts): `packages/hydrogen-sanity/src/context.ts`
- [Sanity provider](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/provider.tsx): `packages/hydrogen-sanity/src/provider.tsx`
- [Query component](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/Query.tsx): `packages/hydrogen-sanity/src/Query.tsx`
- [Client query](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/Query.client.tsx): `packages/hydrogen-sanity/src/Query.client.tsx`
- [Image URL helpers](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/image.ts): `packages/hydrogen-sanity/src/image.ts`
- [Vite integration](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/vite/plugin.ts): `packages/hydrogen-sanity/src/vite/plugin.ts`

### Preview and editing

- [Preview route](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/preview/route.ts): `packages/hydrogen-sanity/src/preview/route.ts`
- [Preview session](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/preview/session.ts): `packages/hydrogen-sanity/src/preview/session.ts`
- [Visual Editing](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/VisualEditing.client.tsx): `packages/hydrogen-sanity/src/visual-editing/VisualEditing.client.tsx`
- [Live mode](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/LiveMode.client.tsx): `packages/hydrogen-sanity/src/visual-editing/LiveMode.client.tsx`
- [Editing overlays](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx): `packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx`
- [Query registry](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/registry.tsx): `packages/hydrogen-sanity/src/visual-editing/registry.tsx`
- [History adapter](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/hooks/history.ts): `packages/hydrogen-sanity/src/visual-editing/hooks/history.ts`
- [Refresh handler](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/hydrogen-sanity/src/visual-editing/hooks/refresh.ts): `packages/hydrogen-sanity/src/visual-editing/hooks/refresh.ts`

### Sanity Studio

- [Studio configuration](https://github.com/sanity-io/hydrogen-sanity/blob/main/packages/sanity-config/sanity.config.ts): `packages/sanity-config/sanity.config.ts`
- [Content schemas](https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/schemaTypes): `packages/sanity-config/src/schemaTypes`
- [Studio structure](https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/structure): `packages/sanity-config/src/structure`

### Shopify content

- [Shopify documents](https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/schemaTypes/objects/shopify): `packages/sanity-config/src/schemaTypes/objects/shopify`
- [Shopify Studio tools](https://github.com/sanity-io/hydrogen-sanity/tree/main/packages/sanity-config/src/plugins/customDocumentActions): `packages/sanity-config/src/plugins/customDocumentActions`

### Other components

- **Storefront developer**
- **Sanity API**
- **Sanity Studio**
- **Shopify**

## Connections

- Storefront developer → Request context: configures (evidence: `README.md`)
- Request context → Sanity API: creates client (evidence: `packages/hydrogen-sanity/src/context.ts`)
- Request context → Sanity provider: provides context (evidence: `packages/hydrogen-sanity/src/context.ts`)
- Request context → Preview session: checks preview state (evidence: `packages/hydrogen-sanity/src/context.ts`)
- Query component → Client query: loads live query (evidence: `packages/hydrogen-sanity/src/Query.tsx`)
- Client query → Query registry: registers query
- Client query → Sanity API: fetches updates
- Storefront developer → Query component: renders content (evidence: `README.md`)
- Storefront developer → Image URL helpers: uses image helpers (evidence: `README.md`)
- Storefront developer → Vite integration: configures plugin (evidence: `README.md`)
- Storefront developer → Preview route: enables preview (evidence: `README.md`)
- Preview route → Preview session: commits session (evidence: `packages/hydrogen-sanity/src/preview/route.ts`)
- Sanity Studio → Preview route: validates preview URL (evidence: `packages/hydrogen-sanity/src/preview/route.ts`)
- Visual Editing → Editing overlays: renders overlays (evidence: `packages/hydrogen-sanity/src/visual-editing/VisualEditing.client.tsx`)
- Visual Editing → Live mode: enables live mode (evidence: `packages/hydrogen-sanity/src/visual-editing/VisualEditing.client.tsx`)
- Editing overlays → History adapter: uses history (evidence: `packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx`)
- Editing overlays → Refresh handler: uses refresh (evidence: `packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx`)
- Editing overlays → Query registry: checks loaders (evidence: `packages/hydrogen-sanity/src/visual-editing/Overlays.client.tsx`)
- Sanity Studio → Visual Editing: drives editing (evidence: `README.md`)
- Studio configuration → Content schemas: registers schemas (evidence: `packages/sanity-config/src/schemaTypes/index.ts`)
- Studio configuration → Studio structure: configures navigation
- Content schemas → Shopify documents: defines commerce types (evidence: `packages/sanity-config/src/schemaTypes/index.ts`)
- Shopify Studio tools → Shopify: links documents