Astro β ImageKit integration + component
An opinionated toolset for using ImageKit.io with your Astro website.
Warning: Experimental
Installation
pnpm astro add astro-imagekit
βORβ
pnpm i astro-imagekit
And in astro.config.mjs
:
import { defineConfig } from 'astro/config';
import dotenv from 'dotenv';
dotenv.config();
import imagekit from 'astro-imagekit';
export default defineConfig({
integrations: [
imagekit(),
],
});
Don't forget to setup the environment variables.
Behaviors
Precepts
- Media library is transparently mapped between remote and local
- No versionning awareness
- No unique file-name id. appending (e.g
/path/to/my-img_g1bB3riIsSH.png
)
- Local files are the single source of truth
./content
base folder (configurable) is ignored in git repo.
- Purposedly dumbed down workflow (ImageKit is very powerful)
Once, at project launch (dev.)
- Scan local files
- Check if each local file path for presence in remote inde
- If missing, upload it
During development
- A media in
./content
is changed by user (captured by Vite server)
- File is uploaded, hard replacing the old one
With image component
- Retrieval options are passed:
- File path, relative to
./content
- Image provider transforms
During local build / CI
- Nothing is done, everything is already outsourced!
Synchronization model
Project architecture can look like this:
Local
./my-astro-project/
βββ src/
βββ ...
βββ content/ <ββ .gitignore'd (Independent content delivery life-cycle)
β β
β βββ posts/
β βββ ...
β β βββ foo.md <ββ Ignored, only media binaries are handled
β β βββ poster.png
β βββ ...
β β
β βββ global
β β βββ logo.png
β β
β βββ ...
βββ ...
Your free to use ./src/content
or anything. It is just a suggestion workflow.
I like to co-locate content assets by purpose, not by arbitrary file format or distribution constraints.
MDs, SVGs or anything are static content too, not the source code (as logic),
which is running your website.
E.g. you might want to outsource your content (CMS / external repo. fetchingβ¦) for editors and designers to live their lives (see astro-remote).
Remote
/my-remote-provider-base (ImageKit)
β
βββ my-designer-sources_my-astro-project/ <ββ Separate sources from distributables
β β
β βββ my-img_g1bBer1sH.png <ββ Default IK behavior (versions, uniquenessβ¦)
βββ ...
β
βββ dist_content/ <ββ Mirrors local `./content` (/!\ force-push to remote)
β β
β βββ posts/
β βββ ...
β β βββ poster.png <ββ 1:1, clean paths
β βββ ...
β β
β βββ global/
β β βββ logo.png
β β
β βββ ...
βββ ...
The first (sources) folder is only for a more real-world demonstration, you can omit it.
E.g. you're not collaborating or don't need sources in the cloud,
you do all your design locally and use ImageKit as a distributables receptacle.
Image component
Note: Work in progress.
A local content index is needed for minimizing API roundtrips (metadata retrieval).
- Smooth default transition: blurred low-res + cross-fade
- Preloading placeholder
- JavaScript disabled fallback
- Automatic ratios (for that, needs to implement local JSON index)
- β¦
Goal is to make the API as terse as possible, with automatic configurations
relying on provider metadatas.
---
import Image from 'astro-imagekit/Image.astro';
---
<Image
path="posts/poster.png"
width="400px"
widths={[100, 400, 800]}
sizes="100vw"
/>
Interface
See ./Props.ts.
Integration
Example of a CLI output, when you launch astro dev
:

Yields:

Environment
Those secrets are used by both the integration and the Image
component.
# REQUIRED
IMAGEKIT_URL_ENDPOINT='https://ik.imagekit.io/$USERNAME/$PUBLISH_DIR'
IMAGEKIT_PUBLIC_KEY='public_**************'
IMAGEKIT_PRIVATE_KEY='private_**************'
# OPTIONAL
IMAGEKIT_BASE_LOCAL_DIR='./content' # <- Default
Note:
./content/**
β> $PUBLISH_DIR/**
Setting a publication directory is optional,
but useful, as you probably want to use your media library for multiple purposes (preproduction files, other projectsβ¦).
If a required variable is missing, the integration will throw an error at startup.
See how to obtain API keys.
CLI
It's not necessary to launch Astro dev. server in order to push sync. medias.
You can do it from the command line:
Usage: imagekit index [options]
Manage library index.
Options:
-e, --env-file <path> Choose which env. file to use. Useful if sourcing from
parent (mono-repo.).
-r, --pull Pull remote index to local cache folder.
-v, --verbose Dump all outputs.
-h, --help display help for command
Usage: imagekit medias [options]
Manage library medias.
Options:
-s, --push Push local files to ImageKit configured distributable
directory.
-e, --env-file <path> Choose which env. file to use.
Useful if sourcing from parent (mono-repo.).
-h, --help display help for command
For whom?
Featureset is focused, it may not suit your workflow.
It is aimed at heavy media databases, think GBs, not MBs.
Nonetheless, you can benefit from it in different scenarios, too.
Goal is to manage your static assets life-cycle independently from code.
That way, you don't have to do convoluted setups, affecting your repo. (Git LFS and alike), while bloating your
CI / Vite builds with tons of redundant medias transformations, uploadsβ¦
Note: Syncing mechanism is pretty basic, so at least, it is more fail-proof vs. a full fledged one.
That means manual interventions if things goes unsynced (you can still go nuclear-mode).
See Behaviors for more insights.
Why?
I've started this as the less painful solution I could think of for my specific
uses cases, consolidating tricks from years of experience chasing the holy grail.
Like many of us, I've struggled with
large binaries management, in close relation to source code.
Reason is they're total antagonists in their own nature.
One have still to wait before a perfect and universal solution to arise π€.
ImageKit
I've chosen this provider because I couldn't wrap my head with some of the
Cloudinary behaviors, and overall the DX was much better with ImageKit.
I don't endorse any of these companies: I'm just seeking for the best
bang-for-the-bucks media service provider,
with the possibility to change at any time if it does not fit the bill anymore.
Originally, I'm reluctant to handing over original, copyrighted assets to
third-parties, but regarding web medias diffusion (images, videos), we can hardly do without
big providers for now, sadly. Self-hosting is hard.
Anyway, ImageKit.io have done some enjoyable APIs, and I'm thankful for that.
TL;DR: I think the fact that ImageKit is more recent helps a lot, DX-wise.
See https://imagekit.io (not affiliated).
πΒ Β JulianCataldo.com