Configure media storage

The admin uploads files to your S3-compatible bucket. StormyCMS stores their URLs and metadata.

Configure the admin

Set these variables in apps/admin/.env:

S3_ENDPOINT=https://s3.amazonaws.com
S3_BUCKET=your-media-bucket
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_REGION=us-east-2

Allow uploads, listing, reads, and deletion in the bucket. Make site images publicly readable.

Keep storage credentials in the admin's server environment. A media record does not grant access to a private object.

Restart the admin. Under Media, upload an image and check its URL. Select it in an image field.

Use an image field

Register a field with field: 'image'. The media picker passes an ImageAsset to your component:

import type { ImageAsset } from '@stormycms/core';

type PhotoProps = { image?: ImageAsset };

export function Photo({ image }: PhotoProps) {
  if (!image?.src) return null;
  return <img src={image.src} alt={image.alt ?? ''} />;
}

The value includes src and optional alt, mediaId, name, and tags. See the core reference.

Use a custom upload flow

Upload the file first, then call createMedia with its URL. Creating or deleting a media record through GraphQL does not upload or delete the stored file.

See the media API reference for record operations and core storage helpers for S3 operations.