Adds responsive WebP/AVIF delivery for EmDash media images with a <picture> component, on-demand Sharp conversion, disk caching, and LCP preload support.

npm install emdash-plugin-modern-images
npx emdash-plugin-modern-images

The CLI creates src/middleware.ts and prints the config snippet for registering the plugin.

Add to astro.config.mjs:

import { modernImagesPlugin } from "emdash-plugin-modern-images";

export default defineConfig({
  integrations: [
    emdash({
      plugins: [modernImagesPlugin()],
    }),
  ],
});

The plugin registration adds the admin settings page. Optimized image delivery is handled by the Astro middleware in step 3.

---
import ModernImage from "emdash-plugin-modern-images/astro/ModernImage";
---

<ModernImage image={post.data.featured_image} />

<!-- With custom sizes and LCP preload -->
<ModernImage image={post.data.featured_image} sizes="(min-width: 768px) 50vw, 100vw" preload />

The component renders a <picture> with AVIF and WebP sources. The browser picks the best format. The original image is the fallback. Widths are clamped to 16-2400, quality is clamped to 30-95, and media storage keys are URL-encoded before being used in generated URLs.

Create src/middleware.ts:

export { onRequest } from "emdash-plugin-modern-images/astro/middleware";

This intercepts /_emdash/api/media/file/...?format=...&w=...&q=... requests and serves cached WebP/AVIF/JPEG variants. On cache miss, it converts the original image with Sharp and stores the result under .cache/images inside UPLOADS_DIR by default.

If you already have middleware, compose:

import { sequence } from "astro:middleware";
import { onRequest as modernImages } from "emdash-plugin-modern-images/astro/middleware";

export const onRequest = sequence(yourMiddleware, modernImages);

External URLs (http:// / https://) are rendered as a plain <img> without optimization.

modernImagesPlugin() is a standard EmDash plugin. Its sandbox/runtime entrypoint only stores admin settings in plugin KV and does not read media files or run Sharp.

Image conversion happens in the exported Astro middleware, which runs in the host Astro app and uses Node APIs. This keeps the plugin descriptor compatible with EmDash standard plugin boundaries while still allowing local filesystem caching for optimized media delivery.

Navigate to /_emdash/admin → Modern Images.

The admin page stores plugin settings in EmDash plugin KV. In the current implementation, generated image URLs are controlled by <ModernImage> props and the middleware request parameters; the middleware does not read plugin KV.

git clone https://github.com/adrianoamalfi/emdash-plugin-modern-images.git
cd emdash-plugin-modern-images
npm install
npm run typecheck
npm test

MIT © Adriano Amalfi