ImageKit & Astro
ImageKit is a real-time media optimization and delivery platform with a global CDN, a built-in Digital Asset Manager (DAM), and a URL-based transformation API for images and videos.
When delivering through ImageKit, you get automatic format conversion (AVIF, WebP), automatic quality, responsive images, AI-powered transformations (background removal, generative fill, upscaling), and adaptive video streaming.
Using ImageKit in Astro
Section titled “Using ImageKit in Astro”The ImageKit Astro SDK registers a custom image service that re-routes Astro’s built-in <Image /> and <Picture /> components, plus Markdown and MDX images, through ImageKit. Local imports continue to be processed by Astro’s built-in Sharp service. This means an existing project can add the integration without breaking existing assets.
The SDK also provides a <Video /> component, an <OgImage /> component for social cards, and a server-side helper for issuing client-side upload tokens.
For pure URL building or browser uploads in any framework, you can also use the lower-level ImageKit JavaScript SDK. For server-side asset management (uploading, listing, deleting, metadata), use the ImageKit Node.js SDK.
Prerequisites
Section titled “Prerequisites”- An existing Astro project
- An ImageKit account
Installing the ImageKit Astro SDK
Section titled “Installing the ImageKit Astro SDK”Install the SDK by running the appropriate command for your package manager:
npm install @imagekit/astropnpm add @imagekit/astroyarn add @imagekit/astroConfiguring your account
Section titled “Configuring your account”Create a new .env file in the root of your project and add your ImageKit credentials:
IMAGEKIT_URL_ENDPOINT="https://ik.imagekit.io/<your_imagekit_id>"
# Only needed if you generate upload auth tokens on the serverPUBLIC_IMAGEKIT_PUBLIC_KEY="<Your Public Key>"IMAGEKIT_PRIVATE_KEY="<Your Private Key>"Then register the integration in astro.config.mjs:
import { defineConfig } from 'astro/config';import imagekit from '@imagekit/astro/integration';
export default defineConfig({ integrations: [imagekit()],});You can also pass urlEndpoint directly to the integration instead of using the environment variable:
imagekit({ urlEndpoint: 'https://ik.imagekit.io/<your_imagekit_id>',}),Using ImageKit images
Section titled “Using ImageKit images”With the integration installed, Astro’s built-in <Image /> and <Picture /> components route requests through ImageKit and apply automatic format and quality optimization, responsive srcset, and lazy loading.
---import { Image } from 'astro:assets';---<Image src="/sample.jpg" width={800} height={600} alt="A sample image"/>The integration adds an additional transformation prop on <Image />, <Picture />, and getImage() for applying any ImageKit transformation (e.g. cropping, focus, AI effects, overlays):
---import { Image } from 'astro:assets';---<Image src="/portrait.jpg" width={500} height={500} alt="Cropped portrait" transformation={[{ width: 500, height: 500, focus: 'face' }]}/>The component-level width and height set the rendered HTML dimensions. The values inside transformation control the ImageKit server-side resize.
AI-powered transformations
Section titled “AI-powered transformations”ImageKit transformations include AI effects that can be applied through the same transformation prop:
---import { Image } from 'astro:assets';---<!-- Remove background --><Image src="/product.jpg" width={500} height={500} alt="Product with background removed" transformation={[{ aiRemoveBackground: true }]}/>
<!-- Upscale a low-resolution image --><Image src="/thumbnail.jpg" width={1024} height={1024} alt="Upscaled image" transformation={[{ aiUpscale: true }]}/>
<!-- Generative fill to extend an image to a new aspect ratio --><Image src="/portrait.jpg" width={1600} height={900} alt="Image extended with generative fill" transformation={[ { width: 1600, height: 900, cropMode: 'pad_resize', background: 'genfill' }, ]}/>
<!-- AI drop shadow --><Image src="/product.png" width={500} height={500} alt="Product with AI drop shadow" transformation={[{ aiDropShadow: true }]}/>See the supported transformations reference in ImageKit documentation for the full list, including overlays, smart cropping (focus: 'auto', focus: 'face'), and other effects.
Using ImageKit videos
Section titled “Using ImageKit videos”Add videos to your .astro components with the <Video /> component. It accepts standard HTML video attributes alongside ImageKit-specific props such as transformation and urlEndpoint.
---import { Video } from '@imagekit/astro';---<Video src="/sample.mp4" width={1280} height={720} controls/>To resize the video on ImageKit’s side, pass dimensions inside transformation:
<Video src="/sample.mp4" width={640} height={360} transformation={[{ width: 640, height: 360 }]} controls/>ImageKit Video Player
Section titled “ImageKit Video Player”The @imagekit/video-player package exports a dedicated Astro integration through the @imagekit/video-player/astro subpath. It provides a native IKVideoPlayer Astro component with full TypeScript types (IKPlayerOptions, SourceOptions). You can use it directly in .astro files without any framework adapter.
The player is built on Video.js and includes AI-generated subtitles and chapters, automatic translation into 50+ languages, word-level karaoke-style highlighting, seek thumbnails, a floating sticky player, and adaptive bitrate streaming (HLS/DASH). No manual transcription work is required.
Install the package:
npm install @imagekit/video-playerpnpm add @imagekit/video-playeryarn add @imagekit/video-playerThen use the IKVideoPlayer component in any .astro file:
---import { IKVideoPlayer } from '@imagekit/video-player/astro';import '@imagekit/video-player/styles.css';
const ikOptions = { imagekitId: 'YOUR_IMAGEKIT_ID', seekThumbnails: true,};
const source = { src: 'https://ik.imagekit.io/your_imagekit_id/video.mp4', chapters: true, // AI-generated chapter markers textTracks: [{ autoGenerate: true, // AI speech-to-text subtitles default: true, highlightWords: true, // word-level highlighting translations: [ { langCode: 'es', label: 'Spanish' }, { langCode: 'fr', label: 'French' }, ], }],};---
<IKVideoPlayer ikOptions={ikOptions} source={source} />With chapters: true, the player auto-generates chapter markers from the video content. Setting autoGenerate: true in textTracks creates AI speech-to-text subtitles without any .srt files. Each entry in translations adds an automatically generated subtitle track in that language.
The Video Player SDK is currently in beta. Test thoroughly before using it in production. See the Video Player overview in ImageKit documentation for the full list of options, including playlists, shoppable videos, and signed URL support.
Generating Open Graph image URLs
Section titled “Generating Open Graph image URLs”Use the <OgImage /> component to render OpenGraph and Twitter Card <meta> tags pointing at an ImageKit-optimized image. Place it inside your layout’s <head>.
---import { OgImage } from '@imagekit/astro';---<html> <head> <OgImage src="/og-banner.jpg" title="My page title" description="Preview description for social cards" alt="OG image description" /> </head> <body><slot /></body></html>