Astro ImageKit SDK

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

npm install @imagekit/javascript

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

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

IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_imagekit_id

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

export default defineConfig({
  integrations: [
    imagekit({
      urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
    }),
  ],
});

---
import { Image } from 'astro:assets';
---

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

---
import { Image } from 'astro:assets';
---

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

---
import { Image } from 'astro:assets';
---

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

---
import { Image, Picture } from 'astro:assets';
---

<!-- Quality presets (low | mid | high | max) map to ImageKit q-25/50/75/100 -->
<Image src="/photo.jpg" alt="" width={800} height={600} quality="high" />

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

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

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

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

<!-- <Picture> works the same way -->
<Picture src="/photo.jpg" alt="" widths={[400, 800, 1200]} formats={['avif', 'webp']} />

<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"
/>

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

<Video
  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 } from '@imagekit/astro';
import { buildSrc } from '@imagekit/javascript';

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 'astro:assets';
---

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

<!-- Density-based srcset for fixed-size elements like icons or logos -->
<Image src="/icon.png" alt="App icon" width={100} height={100} densities={[1, 1.5, 2]} />

<!-- Explicit widths + sizes for fluid images -->
<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"
/>

<!-- Layout-based responsive (Astro 5+) -->
<Image src="/hero.jpg" alt="" width={1920} height={1080} layout="full-width" />
<Image src="/article.jpg" alt="" width={800} height={600} layout="constrained" />

<!-- 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"
  width={1200}
  height={630}
  loading="eager"
  fetchpriority="high"
  decoding="sync"
/>

---
import { Image } from 'astro:assets';
import { buildSrc } from '@imagekit/javascript';

const placeholderUrl = buildSrc({
  urlEndpoint: 'https://ik.imagekit.io/your_imagekit_id',
  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'"
/>

---
import { Image } from 'astro:assets';
---

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

<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 { 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>...</body>
</html>

<meta property="og:title" content="..." />
<meta property="og:description" content="..." />
<meta property="og:type" content="website" />
<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 name="twitter:title" content="..." />
<meta name="twitter:description" content="..." />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="..." />
<meta name="twitter:image:alt" content="..." />

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

const ogImage = getOgImageUrl({
  src: '/og-banner.jpg',
  transformation: [{ width: 1200, height: 630 }],
});
---

<meta property="og:image" content={ogImage} />

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. Expiry in seconds; max 1 hour in the future. Default: 30 minutes.
    // token: 'random-token', // Optional. Auto-generated UUID if omitted.
  });

  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/javascript';

      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>

npm install -D @imagekit/nodejs

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import ImageKit from '@imagekit/nodejs';
import type { Files } from '@imagekit/nodejs/resources/files/files';

const client = new ImageKit({
  privateKey: import.meta.env.IMAGEKIT_PRIVATE_KEY,
});

const gallery = defineCollection({
  loader: async () => {
    const assets = await client.assets.list({
      type: 'file',       // exclude folders
      fileType: 'image',  // only image files
      skip: 0,
      limit: 50,
    });

    return assets
      .filter((asset): asset is Files.File =>
        asset.type === 'file' && !!asset.fileId && !!asset.url
      )
      .map((asset) => ({
        id: asset.fileId ?? '',
        url: asset.url ?? '',
        width: asset.width ?? 0,
        height: asset.height ?? 0,
        name: asset.name ?? '',
        tags: asset.tags ?? [],
      }));
  },
  schema: z.object({
    url: z.string().url(),
    width: z.number(),
    height: z.number(),
    name: z.string(),
    tags: z.array(z.string()),
  }),
});

export const collections = { gallery };

---
import { Image } from 'astro:assets';
import { getCollection } from 'astro:content';

const photos = await getCollection('gallery');
---

{photos.map(({ data }) => (
  <Image
    src={data.url}
    width={data.width}
    height={data.height}
    alt={data.name}
    transformation={[{ width: 400, height: 300, focus: 'auto' }]}
  />
))}

<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' },
  ]}
/>