@airdraft/plugin-media

Media management plugin for Airdraft. Adds binary file upload/storage, a browsable media library, and automatic URL resolution for image and media schema fields.

Installation

npm install @airdraft/plugin-media

You also need a storage adapter: @airdraft/media-adapter-local for local development, @airdraft/media-adapter-files-sdk for S3 / Airdraft Cloud, or @airdraft/media-adapter-github for repo-backed media files.

Usage

withAutoMedia (recommended)

Auto-selects the right adapter based on environment variables. Uses the Files SDK (S3) when AWS_S3_BUCKET_NAME is set, otherwise falls back to the local adapter. GitHub repo-backed media is available via explicit selection with storageBackend: 'github' or AIRDRAFT_MEDIA_ADAPTER=github.

import { withAutoMedia } from '@airdraft/plugin-media'

const media = await withAutoMedia({ storageAdapter: adapter })

export default defineConfig({
  adapter,
  plugins: [media],
})

GitHub backend example:

const media = await withAutoMedia({
  storageAdapter: adapter,
  storageBackend: 'github',
})

This stores binary media directly in the repository using the same GitHub App credentials or token-relay environment variables already used for content storage.

withMedia (manual)

Explicit adapter selection:

import { withMedia } from '@airdraft/plugin-media'
import { LocalMediaAdapter } from '@airdraft/media-adapter-local'

const media = withMedia({
  adapter: new LocalMediaAdapter({ root: './public' }),
  storageAdapter: adapter,          // content adapter for sidecar metadata
  prefix: 'uploads',               // key prefix for uploaded files
  allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
  maxSize: 5 * 1024 * 1024,        // 5 MB
})

Options

| Option | Type | Default | Description | |---|---|---|---| | adapter | MediaAdapter | required | Binary storage adapter | | storageAdapter | StorageAdapter | — | Content adapter for sidecar metadata (enables full library mode) | | prefix | string | 'uploads' | Key prefix for uploaded files | | allowedTypes | string[] | ['image/jpeg', 'image/png', 'image/webp', 'image/gif', 'image/svg+xml'] | Accepted MIME types | | maxSize | number | — | Max upload size in bytes |

API Routes

The plugin registers the following routes on the CMS handler:

| Method | Path | Description | |---|---|---| | POST | /media/upload | Upload a file (multipart/form-data) | | GET | /media | List media items (supports prefix, limit, cursor) | | GET | /media/:key | Get a single media item's metadata | | PATCH | /media/:key | Update media metadata (alt, caption, title, tags) | | DELETE | /media/:key | Delete a file and its sidecar | | GET | /media/:key/url | Resolve a fresh signed URL for a key |

transformEntry hook

The plugin injects companion fields for every image and media field in a collection when an entry is read:

| Field type | Injected companions | |---|---| | image or media (single) | {field}_url: string, {field}_media: MediaItem | | media (multiple) | {field}_urls: string[], {field}_medias: MediaItem[] |

URLs are resolved fresh on every read (pre-signed S3 URLs are always current).

Changelog

See CHANGELOG.md.