How to Integrate ImageKit with Your Headless CMS

What is ImageKit?

ImageKit is a DAM and media delivery platform for images and videos. Teams use it for uploads, URL-based transformations, format conversion, responsive delivery, CDN-backed assets, media search, metadata, and asset organization. It’s commonly used by ecommerce, publishing, marketplace, and SaaS teams that need fast media delivery without hand-editing every image size.

Why integrate ImageKit with a headless CMS?

Media breaks down fast when content and assets live in separate systems. A product editor updates a hero image in one place, a developer copies the asset URL into another, and the frontend still needs separate logic for resizing, WebP or AVIF delivery, alt text, and cache behavior. Multiply that by 4 channels, 20 locales, and hundreds of SKUs, and you get stale images, missing metadata, and slow pages.

Architecture overview

A typical Sanity and ImageKit integration starts when an editor publishes content in Sanity Studio. The document and its image references are written to the Content Lake. A GROQ-powered webhook listens for the document types you care about, such as product, article, landingPage, or campaign. The webhook sends the changed document ID to a Sanity Function or your own API route. That server-side code uses @sanity/client to fetch the full document with a GROQ query, including joined image asset URLs and referenced fields like category names or campaign slugs. Then it calls ImageKit’s Upload API through the ImageKit SDK, passing the Sanity image URL as the file, plus a fileName, folder, tags, and customMetadata. ImageKit ingests the remote image, stores it in its media library, applies delivery settings, and returns a CDN URL. Your frontend can then render ImageKit URLs directly, or you can write the returned ImageKit fileId and URL back to Sanity if editors need to see the delivery asset in Sanity Studio. For end users, the final page loads media from ImageKit’s CDN with URL parameters for width, crop, quality, and format, while structured content still comes from Sanity.

Common use cases

Step-by-step integration

1. 1

   Create your ImageKit project

   Sign in to ImageKit, create or select a media library, and copy your public key, private key, and URL endpoint from the developer settings. Decide your folder pattern early, such as /sanity/products, /sanity/articles, or /sanity/campaigns.

2. 2

   Install the SDKs

   Install ImageKit’s Node.js SDK and the Sanity client in the server-side environment that will receive webhooks: npm install imagekit @sanity/client.

3. 3

   Model media context in Sanity Studio

   Add image fields with alt text, caption, usage rights, focal point notes, and any routing fields your frontend needs. For products, include fields like sku, slug, category references, and mainImage. For articles, include title, slug, heroImage, author, and topic references.

4. 4

   Create a publish trigger

   Set up a Sanity webhook filtered to the document types you want to sync, or use a Sanity Function if you want the sync logic to run inside Sanity’s event system. Send the document ID and mutation type when content is published, updated, or deleted.

5. 5

   Call ImageKit from server-side code

   Use @sanity/client to fetch the document with GROQ, then call imagekit.upload with the Sanity asset URL as the file. Pass folder, tags, and customMetadata so ImageKit search and organization reflect the content structure.

6. 6

   Test the frontend path

   Publish one test document, confirm the asset appears in ImageKit, check tags and custom metadata, and render the returned ImageKit URL with transformation parameters like tr=w-800,f-auto. Test cache behavior, missing images, unpublished content, and deleted documents before rolling it out.

How Sanity + ImageKit works

CMS approaches to ImageKit

Keep building

Explore related integrations to complete your content stack.