Sanity Integration

Cachely has first-class edge-proxy support for Sanity: every Sanity image, file, and API request is cached and served from your your-tenant.cachely.io domain.

SDK runtime status: the @cachely-io/sdk runtime ships built-in provider: "contentful" and provider: "prismic". A built-in provider: "sanity" is not available yet — use the createGenericProvider integration shown below. The Cachely CLI will detect Sanity and write a cachely.config.json, but it will not patch your client; copy the snippet from this page.

Supported URL patterns

Sanity serves all assets from a single CDN domain with different path prefixes for images and files.

Images:

https://cdn.sanity.io/images/{projectId}/{dataset}/{assetId}-{width}x{height}.{format}

Files (video, PDF, etc.):

https://cdn.sanity.io/files/{projectId}/{dataset}/{hash}.{extension}

Both are rewritten to:

https://your-tenant.cachely.io/{assetId-or-hash}.{ext}

Tenant setup

When creating your tenant, select Sanity as the CMS type and provide your project ID:

Two origins are automatically configured:

• Image origin: https://cdn.sanity.io/images/{projectId}/production
• File origin: https://cdn.sanity.io/files/{projectId}/production

The dataset defaults to production. If your project uses a different dataset (e.g. staging), use the custom origin override instead of the Project ID field and set both origins manually.

File and video support

Sanity serves images and files from the same domain (cdn.sanity.io) using different path prefixes. Cachely handles both automatically:

• Image requests (jpeg, jpg, png, webp, avif, svg) route to cdn.sanity.io/images/…
• File requests (mp4, webm, mov, m4v, pdf) route to cdn.sanity.io/files/…

Range requests for video seeking and streaming are fully supported.

Cachely SDK

Install the Cachely SDK to route Sanity API and asset requests through your edge domain:

npm install @cachely-io/sdk

Basic usage

Sanity is supported via the SDK's generic provider:

import { createGenericProvider, createCachelyFetch } from '@cachely-io/sdk'
import { createClient } from '@sanity/client'

const sanity = createGenericProvider({
  id: 'sanity',
  apiHosts: ['*.api.sanity.io', '*.apicdn.sanity.io'],
  assetHosts: ['cdn.sanity.io'],
})

const cachelyFetch = createCachelyFetch({
  tenant: 'your-tenant',
  provider: sanity,
})

const client = createClient({
  projectId: 'your-project-id',
  dataset: 'production',
  apiVersion: '2021-10-21',
  useCdn: true,
  fetch: cachelyFetch as any,
})

const data = await client.fetch('*[_type == "page"]{ title, image }')

Rewriting URLs without intercepting fetch

If you can't replace the fetch implementation, use createCachelyUrlRewriter:

import { createCachelyUrlRewriter, createGenericProvider } from '@cachely-io/sdk'

const sanity = createGenericProvider({
  id: 'sanity',
  apiHosts: ['*.api.sanity.io', '*.apicdn.sanity.io'],
  assetHosts: ['cdn.sanity.io'],
})

const rewrite = createCachelyUrlRewriter({ tenant: 'your-tenant', provider: sanity })

const { url } = rewrite('https://cdn.sanity.io/images/your-project-id/production/photo.jpg?w=800')
// → https://your-tenant.cachely.io/images/your-project-id/production/photo.jpg?w=800

Sanity Image Pipeline

Sanity's image pipeline adds query parameters like ?w=800&h=600&fit=crop&auto=format for on-the-fly image transformations. When assets are proxied through Cachely:

• The edge cache strips query parameters from the cache key for image types
• This means all image transformation variants share the same cache entry
• If you rely on Sanity's image pipeline transformations, the first cached version will be served for all variants

If you need different image sizes, apply transformations on the client side or serve each size from a different path.

Advanced

For more control — disabling proxying selectively, classifying URLs by hand, registering custom providers — see the Cachely SDK reference.