Astro ImageKit SDK

npm install @imagekit/astro
# or
pnpm add @imagekit/astro
# or
yarn add @imagekit/astro

// astro.config.mjs
import { defineConfig } from 'astro/config';
import imagekit from '@imagekit/astro/integration';

export default defineConfig({
  integrations: [imagekit()],
});

# Preferred — available in both server and client code
PUBLIC_IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_imagekit_id

# Server-only fallback
IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_imagekit_id

export default defineConfig({
  integrations: [
    imagekit({
      urlEndpoint: import.meta.env.PUBLIC_IMAGEKIT_URL_ENDPOINT,
      transformationPosition: 'query', // or 'path'
      domains: ['assets.example.com'],
      remotePatterns: [{ protocol: 'https', hostname: 'assets.example.com', pathname: '/**' }],
    }),
  ],
});

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: '@imagekit/astro/image-service',
      config: {
        urlEndpoint: import.meta.env.PUBLIC_IMAGEKIT_URL_ENDPOINT,
        transformationPosition: 'query',
      },
    },
    domains: ['ik.imagekit.io'],
    remotePatterns: [{ protocol: 'https', hostname: 'ik.imagekit.io', pathname: '/**' }],
  },
});

---
import { Image } from '@imagekit/astro';
---

<Image
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/default-image.jpg"
  alt="A sample image"
  width={400}
  height={300}
/>

---
import { Image } from '@imagekit/astro';
---

<Image
  src="/default-image.jpg"
  alt="A sample image"
  width={400}
  height={300}
/>

<Image
  src="/default-image.jpg"
  alt="Resized image"
  transformation={[{ width: 600, height: 400, focus: "auto" }]}
  width={600}
  height={400}
/>

<!-- Format and quality -->
<Image
  src="/photo.jpg"
  alt="WebP image"
  format="webp"
  quality={80}
  width={800}
  height={600}
/>

<!-- Layout modes (Astro 5+) -->
<Image
  src="/hero.jpg"
  alt="Full-width hero"
  layout="full-width"
  width={1200}
  height={630}
/>

<Image
  src="/hero.jpg"
  alt="Constrained hero"
  layout="constrained"
  width={800}
  height={400}
/>

<!-- Density-based srcset -->
<Image
  src="/icon.png"
  alt="Retina icon"
  densities={[1.5, 2]}
  width={100}
  height={100}
/>

<!-- Explicit widths with sizes -->
<Image
  src="/photo.jpg"
  alt="Responsive photo"
  widths={[240, 540, 720]}
  sizes="(max-width: 360px) 240px, (max-width: 720px) 540px, 720px"
  width={720}
  height={480}
/>

<!-- Loading and priority -->
<Image
  src="/hero.jpg"
  alt="Above the fold"
  loading="eager"
  fetchpriority="high"
  width={1200}
  height={630}
/>

<Image
  src="/https://www.example.com/images/hero.jpg"
  alt="Hero image from web proxy"
  width={1200}
  height={630}
  transformation={[{ width: 1200, height: 630, }]}
/>

https://ik.imagekit.io/your_imagekit_id/https://www.example.com/images/hero.jpg?tr=w-1200,h-630

<Image
  src="/https://www.example.com/images/banner.jpg"
  alt="Banner from web proxy"
  width={900}
  height={400}
  transformation={[{ width: 900, height: 400 }]}
  transformationPosition="path"
/>

https://ik.imagekit.io/your_imagekit_id/tr:w-900,h-400/https://www.example.com/images/banner.jpg

<Image
  src="/https://www.example.com/images/product.jpg"
  alt="Product image"
  width={800}
  height={600}
  layout="constrained"
/>

---
import { Video } from '@imagekit/astro';
---

<Video
  urlEndpoint="https://ik.imagekit.io/your_imagekit_id"
  src="/sample-video.mp4"
  width={640}
  height={360}
  controls
/>

<Video
  src="/sample-video.mp4"
  transformation={[{ width: 640, height: 360 }]}
  width={640}
  height={360}
  controls
/>

<Video
  src="/sample-video.mp4"
  width={640}
  height={360}
  controls
  autoplay
  loop
  muted
  preload="none"
  poster="https://ik.imagekit.io/your_imagekit_id/video-thumbnail.jpg"
/>

---
import { Video, buildSrc } from '@imagekit/astro';

const posterUrl = buildSrc({
  urlEndpoint: "https://ik.imagekit.io/your_imagekit_id",
  src: "/video.mp4/ik-thumbnail.jpg",
});
---

<Video
  src="/video.mp4"
  controls
  preload="none"
  poster={posterUrl}
  width={640}
  height={360}
/>

---
import { Image } from '@imagekit/astro';
---

<Image
  src="/profile.png"
  alt="Profile picture"
  width={500}
  height={500}
  transformation={[{ width: 500, height: 500 }]}
/>

<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1200}
  height={630}
  priority
/>

<!-- Output HTML includes -->
<!-- loading="eager" decoding="sync" fetchpriority="high" -->

<!-- Eager loading -->
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1200}
  height={630}
  loading="eager"
  decoding="sync"
  fetchpriority="high"
/>

<!-- Lazy loading (default) -->
<Image
  src="/article-image.jpg"
  alt="Article image"
  width={800}
  height={600}
  loading="lazy"
  decoding="async"
/>

<!-- WebP format with high quality -->
<Image
  src="/photo.jpg"
  alt="High quality photo"
  width={800}
  height={600}
  format="webp"
  quality="high"
/>

<!-- AVIF format for maximum compression -->
<Image
  src="/photo.jpg"
  alt="Compressed photo"
  width={800}
  height={600}
  format="avif"
  quality={85}
/>

<!-- Quality presets: low, mid, high, max -->
<Image
  src="/photo.jpg"
  alt="Balanced quality"
  width={800}
  height={600}
  quality="mid"
/>

<Image
  src="/photo.jpg"
  alt="Responsive photo"
  width={800}
  height={600}
/>

<!-- Generated output includes srcset with multiple widths -->
<!-- srcset="...?tr=w-640/... 640w, ...?tr=w-750/... 750w, ...?tr=w-828/... 828w, ..., ...?tr=w-1920/... 1920w" -->
<!-- sizes="100vw" -->

<!-- Pixel density variants for crisp display on high-DPI screens -->
<Image
  src="/icon.png"
  alt="App icon"
  width={100}
  height={100}
  densities={[1, 1.5, 2]}
/>

<!-- Generated: icon.png?tr=w-100 1x, icon.png?tr=w-150 1.5x, icon.png?tr=w-200 2x -->

<!-- Custom widths for specific design breakpoints -->
<Image
  src="/photo.jpg"
  alt="Gallery image"
  width={800}
  height={600}
  widths={[300, 600, 900, 1200]}
  sizes="(max-width: 640px) 300px, (max-width: 1024px) 600px, 900px"
/>

<!-- Generated srcset includes only specified widths -->
<!-- srcset="...?tr=w-300/... 300w, ...?tr=w-600/... 600w, ...?tr=w-900/... 900w, ...?tr=w-1200/... 1200w" -->

<!-- Constrained layout: scales down but never up -->
<Image
  src="/photo.jpg"
  alt="Article image"
  width={800}
  height={600}
  layout="constrained"
/>

<!-- Full width: always fills container width -->
<Image
  src="/hero.jpg"
  alt="Hero image"
  width={1920}
  height={1080}
  layout="full-width"
/>

<!-- Fixed: maintains exact dimensions, supports density scaling -->
<Image
  src="/logo.png"
  alt="Logo"
  width={200}
  height={100}
  layout="fixed"
/>

<!-- None: no automatic responsive behavior -->
<Image
  src="/custom.jpg"
  alt="Custom handling"
  width={400}
  height={300}
  responsive={false}
/>

<Image
  src="/photo.jpg"
  alt="Custom breakpoints"
  width={800}
  height={600}
  deviceBreakpoints={[320, 480, 768, 1024, 1280]}
  imageBreakpoints={[48, 96, 192, 384]}
/>

<Image
  src="/photo.jpg"
  alt="Non-responsive"
  width={800}
  height={600}
  responsive={false}
/>

<!-- No srcset or sizes generated -->

<!-- Example: layout has higher precedence than ImageKit responsive -->
<Image
  src="/photo.jpg"
  width={800}
  height={600}
  layout="constrained"
  responsive={true}  <!-- Will be overridden by layout -->
/>
<!-- Result: uses layout-based srcset, not ImageKit responsive -->

<!-- Example: widths + sizes override ImageKit responsive -->
<Image
  src="/photo.jpg"
  width={800}
  height={600}
  widths={[300, 600, 900]}
  sizes="(max-width: 640px) 300px, 600px"
  responsive={true}  <!-- Will be overridden by widths -->
/>
<!-- Result: uses Astro's width-based srcset -->

<!-- Default: lazy loading -->
<Image
  src="/profile.png"
  alt="Lazy loaded"
  width={500}
  height={500}
/>

<!-- Eager loading for above-the-fold images -->
<Image
  src="/hero.jpg"
  alt="Hero image"
  loading="eager"
  width={1200}
  height={630}
/>

---
import { Image, buildSrc } from '@imagekit/astro';

const placeholderUrl = buildSrc({
  src: "/default-image.jpg",
  transformation: [
    {
      quality: 10,
      blur: 90,
    },
  ],
});

const placeholderStyle = `background-image: url(${placeholderUrl}); background-size: cover; background-repeat: no-repeat; background-position: center;`;
---

<Image
  src="/default-image.jpg"
  alt="Image with placeholder"
  width={400}
  height={400}
  loading="lazy"
  style={placeholderStyle}
  onload="this.style.backgroundImage='none'"
/>

---
// src/components/ImageWithPlaceholder.astro
import { Image, buildSrc } from '@imagekit/astro';
import type { ImageProps } from '@imagekit/astro';

type Props = ImageProps & Partial<HTMLImageElement>;

const { src, urlEndpoint, transformation, onload: userOnload, style: userStyle, ...rest } = Astro.props;

const resolvedEndpoint = urlEndpoint ?? import.meta.env?.PUBLIC_IMAGEKIT_URL_ENDPOINT ?? import.meta.env?.IMAGEKIT_URL_ENDPOINT;

const placeholderUrl = buildSrc({
  urlEndpoint: resolvedEndpoint,
  src: src as string,
  transformation: [
    ...(transformation || []),
    { quality: 10, blur: 90 },
  ],
});

const placeholderStyle = `background-image: url(${placeholderUrl}); background-size: cover; background-repeat: no-repeat; background-position: center;`;
const combinedStyle = userStyle ? `${placeholderStyle} ${userStyle}` : placeholderStyle;

const clearPlaceholder = `this.style.backgroundImage='none';`;
const combinedOnload = userOnload
  ? `${clearPlaceholder} (${userOnload}).call(this, event);`
  : clearPlaceholder;
---

<Image
  src={src}
  urlEndpoint={urlEndpoint}
  transformation={transformation}
  {...rest}
  style={combinedStyle}
  onload={combinedOnload}
/>

---
import ImageWithPlaceholder from '../components/ImageWithPlaceholder.astro';
---

<ImageWithPlaceholder
  src="/default-image.jpg"
  alt="Image with placeholder"
  width={400}
  height={400}
  loading="lazy"
/>

---
import { Image } from '@imagekit/astro';
---

<Image
  src="/photo.jpg"
  alt="Chained transformations"
  transformation={[
    { width: 400, height: 300 },  // First: resize
    { rotation: 90 },             // Then: rotate
  ]}
  width={400}
  height={300}
/>

<Image
  src="/background.jpg"
  alt="Background with image overlay"
  width={600}
  height={400}
  transformation={[
    { overlay: { type: "image", input: "logo.png" } }
  ]}
/>

<Image
  src="/background.jpg"
  alt="Background with resized overlay"
  width={600}
  height={400}
  transformation={[
    {
      overlay: {
        type: "image",
        input: "logo.png",
        transformation: [{ width: 100, height: 100 }]
      }
    }
  ]}
/>

<Image
  src="/background.jpg"
  alt="Background with text"
  width={600}
  height={400}
  transformation={[
    {
      overlay: {
        type: "text",
        text: "Hello, ImageKit!",
        transformation: [{ fontSize: 20, fontColor: "FF0000" }]
      }
    }
  ]}
/>

<Image
  src="/background.jpg"
  alt="Background with color overlay"
  width={600}
  height={400}
  transformation={[
    {
      overlay: {
        type: "solidColor",
        color: "FF0000",
        transformation: [{ width: 100, height: 100 }]
      }
    }
  ]}
/>

<Video
  src="/background.mp4"
  controls
  transformation={[
    {
      overlay: {
        type: "video",
        input: "overlay.mp4",
        timing: { start: 5, duration: 10 }
      }
    }
  ]}
/>

<Video
  src="/background.mp4"
  controls
  transformation={[
    {
      overlay: {
        type: "subtitle",
        input: "subtitle.srt"
      }
    }
  ]}
/>

<Image
  src="/photo.jpg"
  alt="Background removed"
  width={500}
  height={500}
  transformation={[{ aiRemoveBackground: true }]}
/>

<!-- AI Drop Shadow -->
<Image
  src="/product.jpg"
  alt="Product with drop shadow"
  width={500}
  height={500}
  transformation={[{ aiDropShadow: true }]}
/>

<!-- AI Upscale -->
<Image
  src="/small-photo.jpg"
  alt="Upscaled photo"
  width={500}
  height={500}
  transformation={[{ aiUpscale: true }]}
/>

<Image
  src="/photo.jpg"
  alt="Half-width image"
  width={300}
  height={200}
  transformation={[{ width: "iw_div_2" }]}
/>

---
import { getOgImageTags } from '@imagekit/astro/helpers';

const ogTags = getOgImageTags({
  src: '/og-banner.jpg',
  title: 'My Page Title',
  description: 'Preview description for social cards',
  alt: 'OG image description',
  twitterCard: 'summary_large_image',
  transformation: [{ width: 1200, height: 630 }],
});
---

<html>
<head>
  {ogTags.map((tag) => <meta {...tag} />)}
</head>
<body>...</body>
</html>

<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:image" content="..." />
<meta property="og:image:secure_url" content="..." />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="..." />
<meta property="twitter:title" content="..." />
<meta property="twitter:description" content="..." />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content="..." />

IMAGEKIT_PRIVATE_KEY=your_private_key
IMAGEKIT_PUBLIC_KEY=your_public_key

// src/pages/api/upload-auth.ts
import type { APIRoute } from 'astro';
import { getUploadAuthParams } from '@imagekit/astro/server';

export const prerender = false;

export const GET: APIRoute = async () => {
  // Your application logic to authenticate the user
  // For example, you can check if the user is logged in or has the necessary permissions
  // If the user is not authenticated, you can return an error response

  const authParams = getUploadAuthParams({
    privateKey: import.meta.env.IMAGEKIT_PRIVATE_KEY, // Never expose this on client side
    publicKey: import.meta.env.IMAGEKIT_PUBLIC_KEY,
    // expire: 30 * 60, // Optional, controls the expiry time of the token in seconds, maximum 1 hour in the future
    // token: "random-token", // Optional, a unique token for request
  });

  return new Response(JSON.stringify(authParams), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
};

---
// src/pages/upload.astro
---

<html>
<body>
  <input type="file" id="file-input" />
  <button id="upload-btn">Upload</button>
  <div>Upload progress: <progress id="upload-progress" value="0" max="100"></progress></div>
  <pre id="result"></pre>

  <script>
    import {
      upload,
      ImageKitAbortError,
      ImageKitInvalidRequestError,
      ImageKitServerError,
      ImageKitUploadNetworkError,
    } from '@imagekit/astro';

    const fileInput = document.getElementById('file-input') as HTMLInputElement;
    const uploadBtn = document.getElementById('upload-btn') as HTMLButtonElement;
    const progressBar = document.getElementById('upload-progress') as HTMLProgressElement;
    const result = document.getElementById('result') as HTMLPreElement;

    // Create an AbortController instance to provide an option to cancel the upload if needed.
    const abortController = new AbortController();

    /**
     * Authenticates and retrieves the necessary upload credentials from the server.
     */
    const authenticator = async () => {
      const response = await fetch('/api/upload-auth');
      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`Request failed with status ${response.status}: ${errorText}`);
      }
      const data = await response.json();
      const { signature, expire, token, publicKey } = data;
      return { signature, expire, token, publicKey };
    };

    uploadBtn.addEventListener('click', async () => {
      const file = fileInput.files?.[0];
      if (!file) {
        alert('Please select a file to upload');
        return;
      }

      // Retrieve authentication parameters for the upload.
      let authParams;
      try {
        authParams = await authenticator();
      } catch (authError) {
        console.error('Failed to authenticate for upload:', authError);
        return;
      }
      const { signature, expire, token, publicKey } = authParams;

      try {
        const response = await upload({
          // Authentication parameters
          expire,
          token,
          signature,
          publicKey,
          file,
          fileName: file.name,
          // Progress callback to update upload progress
          onProgress: (event) => {
            progressBar.value = (event.loaded / event.total) * 100;
          },
          // Abort signal to allow cancellation of the upload if needed.
          abortSignal: abortController.signal,
        });
        console.log('Upload response:', response);
        result.textContent = JSON.stringify(response, null, 2);
      } catch (error) {
        // Handle specific error types provided by the ImageKit SDK.
        if (error instanceof ImageKitAbortError) {
          console.error('Upload aborted:', error.reason);
        } else if (error instanceof ImageKitInvalidRequestError) {
          console.error('Invalid request:', error.message);
        } else if (error instanceof ImageKitUploadNetworkError) {
          console.error('Network error:', error.message);
        } else if (error instanceof ImageKitServerError) {
          console.error('Server error:', error.message);
        } else {
          console.error('Upload error:', error);
        }
      }
    });
  </script>
</body>
</html>

<Image
  src="/photo.jpg"
  alt="Custom transformation"
  width={500}
  height={500}
  transformation={[
    // @ts-ignore
    { unsupportedTransformation: "value" }
  ]}
/>

<Image
  src="/photo.jpg"
  alt="Raw transformation"
  width={500}
  height={500}
  transformation={[
    { raw: "unsupportedTransformation-value" }
  ]}
/>