Media

Complete reference for @86d-app/media: manage digital assets with folder organization, tagging, bulk operations, and storefront display components.

The media module is your store’s digital asset manager. You upload images, videos, and other files through the platform’s upload API, then use the media module to organize those assets into folders, apply tags, and display them on the storefront. The store-facing components handle images, galleries, and video playback. All create, update, and delete operations require admin access; store endpoints are read-only.

Source: modules/media · npm: @86d-app/media

Installation

npm

npm install @86d-app/media

Then register the module in your store’s config.json:

{
  "modules": ["media"]
}

Configuration

import media from "@86d-app/media";

const module = media({
  maxFileSize: "10485760",
  allowedMimeTypes: "image/png,image/jpeg,image/webp,video/mp4",
});

maxFileSize · string · default: "\"10485760\""

Maximum file size in bytes. Defaults to 10 MB (10485760). This value is a string for module config compatibility.

allowedMimeTypes · string

Comma-separated list of allowed MIME types. Defaults to all types when omitted. Example: "image/png,image/jpeg,image/webp,video/mp4".

File upload

Files are uploaded through the platform’s shared upload endpoint, not through the media module endpoints directly. The upload endpoint is admin-only.

Method	Path	Description
POST	/api/upload	Upload a file (admin only)
DELETE	/api/upload	Delete an uploaded file (admin only)

Supported file types and size limits:

Type	Formats	Max size
Images	JPEG, PNG, WebP, GIF, SVG	4.5 MB
Documents	PDF	10 MB
Video	MP4 and other types per allowedMimeTypes	Per maxFileSize config

After uploading, create an asset record via the admin API to register the file URL in the media library.

Store endpoints

Store endpoints are read-only and publicly accessible.

Method	Path	Description
GET	/media	List assets, filterable by folder, MIME type, and tag
GET	/media/:id	Get a single asset by ID

Admin endpoints

Admin endpoints require authentication.

Assets

Method	Path	Description
GET	/admin/media	List all assets, filterable by folder, MIME type, tag, and search query
POST	/admin/media/create	Create a new asset record
GET	/admin/media/:id	Get an asset by ID
PUT	/admin/media/:id/update	Update asset metadata (name, alt text, tags, folder)
DELETE	/admin/media/:id/delete	Delete an asset
POST	/admin/media/bulk-delete	Bulk-delete multiple assets by ID
POST	/admin/media/move	Move assets to a different folder
GET	/admin/media/stats	Get media library statistics

Folders

Method	Path	Description
GET	/admin/media/folders	List folders, filterable by parentId
POST	/admin/media/folders/create	Create a new folder
PUT	/admin/media/folders/:id	Rename a folder
DELETE	/admin/media/folders/:id/delete	Delete a folder

Components

Add these components to your MDX template files. The media module must be listed in config.json.

ImageDisplay

Displays a single image asset by ID. Fetches the asset, renders it with proper alt text, and optionally shows a caption.

id · string · required

Asset ID to display.

className · string

CSS class applied to the container element.

showCaption · boolean · default: "false"

When true, renders the asset name as a caption below the image.

<ImageDisplay id="asset-123" />

<ImageDisplay id="asset-123" showCaption />

<ImageDisplay id="hero-banner" className="aspect-[21/9] w-full" />

Use ImageDisplay for hero images, content blocks, or anywhere you need to render a single managed image.

---

MediaGallery

Filterable grid of media assets. Images render as thumbnails, videos show a poster frame with a play overlay, and other file types display a label. Supports pagination and item selection. Fetches its own data.

folder · string

Filter assets by folder ID.

type · string

Filter by type: "image", "video", or any MIME type prefix (e.g. "image/png").

tag · string

Filter assets by a single tag.

pageSize · number · default: "12"

Number of items per page.

<MediaGallery />

<MediaGallery type="image" pageSize={8} />

<MediaGallery folder="hero-banners" tag="featured" />

Use MediaGallery on gallery pages, lookbook sections, or anywhere you want a browsable media grid.

---

VideoPlayer

Embedded HTML5 video player. Fetches a video asset by ID and renders it with native browser controls.

id · string · required

Asset ID of the video to play.

autoPlay · boolean · default: "false"

Auto-play the video (muted) when it becomes visible in the viewport.

loop · boolean · default: "false"

Loop playback continuously.

className · string

CSS class applied to the container element.

<VideoPlayer id="promo-video" />

<VideoPlayer id="product-demo" autoPlay loop />

<VideoPlayer id="tutorial" className="max-w-2xl mx-auto" />

Use VideoPlayer for product demo videos, promotional content, or tutorial sections.

---

Types

interface Asset {
  id: string;
  name: string;
  altText?: string;
  url: string;
  mimeType: string;
  size: number;                // in bytes
  width?: number;
  height?: number;
  folder?: string;
  tags: string[];
  metadata: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

interface Folder {
  id: string;
  name: string;
  parentId?: string;           // Supports nested folder hierarchies
  createdAt: Date;
}

interface MediaStats {
  totalAssets: number;
  totalSize: number;           // in bytes
  byMimeType: Record<string, number>;
  byFolder: Record<string, number>;
}

Notes

• Folders support nesting via parentId. Use GET /admin/media/folders?parentId=<id> to list a folder’s children.
• Tags are stored as a JSON string array. You can filter by one tag at a time using the tag query parameter.
• bulkDelete and moveAssets operate on arrays of asset IDs for efficient batch processing.
• getStats() returns totals broken down by MIME type and folder, useful for storage reporting.
• Store endpoints are read-only. All create, update, and delete operations require admin authentication.