# astro-media-kit [](https://www.npmjs.com/package/astro-media-kit) [](https://opensource.org/license/mit) [](https://github.com/kitschpatrol/astro-media-kit/actions/workflows/ci.yml) **Astro components for images and video.** > [!WARNING] > > **This project is under development. It should not be considered suitable for general use until a 1.0 release.** ## Overview This is a small collection of Astro components to help you write minimalist, platonic markup in your content and templates without compromising robust output. `` and `` are designed as **clean super-sets** of Astro's built-in components — every prop Astro accepts is accepted here, and the component adds a handful of extras (dark-mode sources, captions, zoom, background compositing) on top. Both local and remote image sources are supported; remote sources skip the features that require access to the source file on disk (XMP credit extraction, background compositing). It includes: - **Image**\ Superset of Astro's `` with captions, XMP credit extraction, PhotoSwipe zoom, background compositing, and a per-input-format `format` override. - **Picture**\ Superset of Astro's `` with configurable dark mode (OS preference, CSS selector, or disabled), per-input-format `formats` and `fallbackFormat` overrides, and everything `` adds. - **Video**\ Unified player for YouTube, Vimeo, Bunny, Cloudflare Stream, Mux, local files, and generic oEmbed, plus integration with PhotoSwipe zoom. - **Audio**\ Player for SoundCloud, local files, and generic oEmbed. - **Astro Integration**\ Auto-import image assets in `.astro` files (no manual `import` statements), plus optional support for tldraw files via [`unplugin-tldraw`](https://github.com/kitschpatrol/unplugin-tldraw). Apple Photos via [`unplugin-aphex`](https://github.com/kitschpatrol/unplugin-aphex), EXIF stripping, original-file cleanup, and a dev-mode image watermark overlay to help debug responsive images. The components work standalone via direct import, or you can use the Astro integration for streamlined auto-imports and automatic Vite plugin configuration. This library pairs well with [astro-mdx-kit](https://github.com/kitschpatrol/astro-mdx-kit). ## Getting started ### Prerequisites - [Node.js](https://nodejs.org/) 24.16.0 or newer (specifically `^24.16.0 || >=26.3.0`) - [astro](https://www.npmjs.com/package/astro) `^7.3.3` _(peer dependency)_ ### Installation ```bash pnpm add astro-media-kit ``` ### Basic setup The simplest way to use `astro-media-kit` is as an Astro integration. This enables auto-importing of image assets in your `.astro` files so you can write `src="../assets/photo.jpg"` as a string and have it resolved to an ESM import automatically: ```ts // Astro.config.ts import mediaKit from 'astro-media-kit' import { defineConfig } from 'astro/config' export default defineConfig({ image: { // Recommended in most cases — sets a sensible default layout and lets // Astro emit the responsive CSS that makes `widths` / `sizes` work out of // the box. `` and `` inherit these settings via `getImage()`. layout: 'constrained', responsiveStyles: true, }, integrations: [ mediaKit({ // All options are optional — defaults are sensible // autoImport: true, // Enabled by default // tldraw: false, // .tldr file support // aphex: false, // Apple Photos imports // removeOriginals: false, // Delete unused original images after build // stripExif: false, // Strip EXIF/XMP metadata from build-output images // video: false, // Env schema injection for video services // watermark: false, // Dev-mode variant label overlay }), ], }) ``` > [!NOTE] > > In most cases you'll want `image.layout: 'constrained'` and `image.responsiveStyles: true` in your Astro config (as shown above). > > These are Astro's own image options, not part of `mediaKit()` — `` and `` pick them up automatically via their internal calls to `getImage()`, so a responsive `srcset` behaves correctly without per-component overrides. ### Direct component usage You can also import components directly without the integration. In this case, pass imported `ImageMetadata` objects or remote URLs rather than local string paths: ```astro --- import { Image, Picture, Video } from 'astro-media-kit/components' import hero from '../assets/hero.jpg' ---