How to Integrate Imgix with Your Headless CMS

What is Imgix?

Imgix is an image processing and delivery platform that serves images through URL parameters for resizing, cropping, format conversion, compression, and cache control. Teams use it to deliver fast visual experiences across ecommerce, publishing, marketplaces, and SaaS products without manually exporting separate image variants. It sits between your image source, such as a web folder, S3 bucket, Google Cloud Storage bucket, or asset CDN, and the end user.

Why integrate Imgix with a headless CMS?

A headless CMS setup works well for Imgix when image fields are structured instead of buried inside rendered HTML. With Sanity's AI Content Operating System, image references, hotspot data, captions, product relationships, and publish state live as typed JSON in the Content Lake. GROQ can select only the fields Imgix needs, and webhooks can fire when an article, product, or landing page is published. That means your frontend can build Imgix URLs from predictable fields instead of scraping image tags from a page body.

Architecture overview

A typical Sanity and Imgix setup starts with an Imgix Source pointed at the Sanity asset CDN path for your project and dataset, for example https://cdn.sanity.io/images/<projectId>/production. Editors add images, crops, alt text, and references in Sanity Studio. Those values are written as typed JSON into the Content Lake, including the Sanity asset URL and any editorial metadata your frontend needs.

Common use cases

Step-by-step integration

1. 1

   Create your Imgix Source

   In Imgix, create a Source that points to your image origin. For Sanity assets, use a Web Folder Source with a base URL like https://cdn.sanity.io/images/<projectId>/<dataset>. Copy your Imgix domain, such as example.imgix.net, and create an API key with purge access if you'll refresh cached images on publish.

2. 2

   Install the SDKs

   In your integration service or Sanity Function project, install @sanity/client and @imgix/js-core. You'll use @sanity/client to fetch structured image fields with GROQ and @imgix/js-core to build Imgix URLs that match your source path.

3. 3

   Model images in Sanity Studio

   Add image fields with alt text, captions, and hotspot support. For example, an article schema might include heroImage, heroImage.alt, heroImage.caption, and body images. Keep image metadata as fields, not as text pasted into rich text, so Imgix and your frontend can consume it directly.

4. 4

   Create the sync trigger

   Use a Sanity webhook or Function that runs on publish events for documents that contain images, such as article, product, or landingPage. Configure the payload to include the document ID, then fetch the full document inside the handler so you're working with current published data.

5. 5

   Call Imgix from server-side code

   Use GROQ to select image asset URLs and metadata, convert each Sanity CDN URL into the path expected by your Imgix Source, and call Imgix's Purge API for changed originals. If you precompute URLs, generate them with @imgix/js-core and write them to your app cache or search index.

6. 6

   Test the frontend experience

   Render images with srcset values like 320, 640, 960, and 1280 widths, then test in Chrome DevTools on slow 4G and high-DPR screens. Confirm that alt text comes from Sanity, Imgix returns the expected format, and a republished image refreshes after the purge call.

Code example

import {createClient} from '@sanity/client'
import ImgixClient from '@imgix/js-core'
import type {Request, Response} from 'express'

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: '2025-01-01',
  token: process.env.SANITY_READ_TOKEN!,
  useCdn: false
})

const imgix = new ImgixClient({domain: process.env.IMGIX_DOMAIN!})
const sourceBasePath = `/images/${process.env.SANITY_PROJECT_ID}/${process.env.SANITY_DATASET}`

export async function handleSanityPublish(req: Request, res: Response) {
  const id = req.body._id

  const doc = await sanity.fetch(`*[_id == $id][0]{
    title,
    heroImage{alt, asset->{url}},
    gallery[]{asset->{url}}
  }`, {id})

  const urls = [doc?.heroImage?.asset?.url, ...(doc?.gallery || []).map((img: any) => img?.asset?.url)].filter(Boolean)

  for (const url of urls) {
    const path = new URL(url).pathname.replace(sourceBasePath, '')
    const imgixUrl = imgix.buildURL(path, {w: 1200, auto: 'format', q: 75})

    await fetch('https://api.imgix.com/api/v1/purge', {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${Buffer.from(`${process.env.IMGIX_API_KEY}:`).toString('base64')}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({url: imgixUrl})
    })
  }

  res.status(200).json({purged: urls.length})
}

How Sanity + Imgix works

CMS approaches to Imgix

Keep building

Explore related integrations to complete your content stack.