Sanity Integration

Tenant configuration

Select Sanity and configure project ID and dataset. Set image origin to https://cdn.sanity.io/images/{projectId}/{dataset}, file origin to https://cdn.sanity.io/files/{projectId}/{dataset}, and API origin to https://{projectId}.api.sanity.io/v2021-10-21 (match the client API version, or omit the version path).

The adapter preserves full image/file namespace paths. Cachely deduplicates matching configured origin paths. Keep transformation query parameters in the cache key: do not include transformed image extensions in stripQueryParamsFor. Responses can already contain rewritten URLs when JSON transformation is enabled on the tenant.

Official-client SDK adapter

Install @sanity/client (version 7 or 8) and import the dedicated subpath:

import { createCachelySanityClient, createCachelySanityAssetUrl } from '@cachely-io/sdk/sanity'

const client = createCachelySanityClient({
  tenant: 'my-project',
  projectId: 'your-project-id',
  dataset: 'production',
  apiVersion: '2021-10-21', // must match the tenant API origin version
})
const pages = await client.fetch('*[_type == $type]', {type: 'page'})

const assetUrl = createCachelySanityAssetUrl({
  tenant: 'my-project', projectId: 'your-project-id', dataset: 'production',
})
// Apply @sanity/image-url crop/hotspot/size first, then rewrite the resolved URL.
const url = assetUrl('https://cdn.sanity.io/images/your-project-id/production/hash-800x600.jpg?w=400&fm=webp')

Only public, published, short GET queries use Cachely. Authenticated requests, draft/release perspectives, source maps, stega, no-store/no-cache, long POST queries, writes, uploads, listeners and observable APIs remain on the original Sanity client. Changing project, dataset or API version via withConfig bypasses the tenant. Set enabled: false to bypass delivery without rewriting callers.

Configure the tenant API origin with the same /vYYYY-MM-DD as apiVersion, or without a version path. The official SDK adds this path after /~api; Cachely deduplicates matching origin prefixes. Use explicit image fm=webp / fm=jpg variants unless your edge cache explicitly varies Sanity auto=format on Accept. Signed assets are never rewritten. R2 ingestion, Studio hosting, CORS and cache invalidation webhooks are separate infrastructure configuration.

This does not add provider: 'sanity' to the generic fetch registry. Sanity's fetch client setting is RequestInit configuration, not a replacement fetch function.

Image-like uploads under /files/ (for example a JPEG uploaded as a file) remain direct while the deployed edge chooses file origins by extension. Normal images and video/PDF files are supported.

Preview and invalidation

Use a server-only read token for draft preview and return private, no-store for preview HTML and data. A Nuxt webhook can verify Sanity's signature and forward to a secret Cachely generic cache-refresh webhook. Refresh API cache on publish/unpublish/delete. Do not add page HTML caching without corresponding invalidation.