Media Workflow Quickstart

Fast-track guide for daily media operations with Supabase Storage + Keystatic CMS.

🎯 The Two-Step Process

Step 1: Upload to Supabase Storage

Step 2: Reference in Keystatic CMS

🏗️ Your Business Buckets

🚀 Method 1: Supabase Console (Easiest)

For Content Creators & Non-Technical Users

Upload Files:

1. Go to Supabase Dashboard → ld_website project
2. Navigate to Storage → Buckets
3. Choose appropriate bucket (see table above)
4. Click "Upload files"
5. Drag/drop or select your files
6. Upload to organized folder (e.g., logos/, products/, brochures/)

Get URL:

1. Click on uploaded file
2. Copy the Public URL
3. Example: https://mgyzvwmmbtmtllliixue.supabase.co/storage/v1/object/public/website_media/logos/logo-primary.svg

Add to Keystatic:

1. Go to /keystatic → Media Library → Create entry
2. Title: Descriptive name (e.g., "Primary Logo - White Background")
3. Supabase Storage URL: Paste the URL from step above
4. Category: Select matching bucket
5. Alt Text: Describe for accessibility
6. Status: Published
7. Save entry

Use in Content:

1. Edit any page/post in Keystatic
2. In media fields, select from Media Library dropdown
3. Choose your uploaded asset
4. Save and publish

⚡ Method 2: CLI Upload (For Developers)

Bulk Operations & Automation

Single File Upload:

# Navigate to project
cd apps/web

# Upload with auto-optimization
node scripts/bulk-media-upload.mjs \
  --bucket=website_media \
  --folder=./local-assets \
  --destination=products/ \
  --validate=true

Bulk Directory Upload:

# Upload entire folder with filtering
node scripts/bulk-media-upload.mjs \
  --bucket=marketing_media \
  --folder=./marketing-assets \
  --destination=brochures/ \
  --filter=pdf,png,jpg \
  --max-size=25

# The tool outputs Supabase URLs for each file

Quick List & Stats:

# List files in bucket
pnpm media:list --bucket=website_media

# Check storage usage
pnpm media:stats --bucket=marketing_media

# Validate organization
pnpm media:validate --bucket=demonstration_media

📂 Folder Organization Guide

Recommended Structure:

# Website Media (logos, branding, product photos)
website_media/
├── logos/              # Company logos (svg, png)
├── products/           # Product photography
├── team/               # Team headshots
└── branding/           # Brand guidelines, assets

# Marketing Media (downloadable content)
marketing_media/
├── brochures/          # PDF marketing materials  
├── presentations/      # Slide decks (pptx, pdf)
├── videos/             # Marketing videos
└── social/             # Social media graphics

# Demo Media (product demonstrations)
demonstration_media/
├── videos/             # Product demo videos
├── tutorials/          # How-to content
├── screenshots/        # Product screenshots
└── use-cases/          # Customer examples

# General Content (blog, pages)
media_library/
├── blog/               # Blog post images
├── pages/              # Page-specific assets
└── uploads/            # General uploads

🔄 Common Workflows

Adding Product Images:

1. Upload: Console → website_media bucket → products/ folder
2. URL: Copy public URL from uploaded file
3. Keystatic: Media Library → New → Paste URL → Category: "Website Media"
4. Use: Product pages → Select from Media Library dropdown

Marketing Materials:

1. Upload: Console → marketing_media bucket → brochures/ folder
2. URL: Copy public URL (will be used for downloads)
3. Keystatic: Media Library → New → Paste URL → Category: "Marketing Media"
4. Use: Marketing pages → Link to downloadable assets

Blog Content:

1. Upload: Console → media_library bucket → blog/ folder
2. URL: Copy public URL
3. Keystatic: Media Library → New → Paste URL → Category: "Media Library"
4. Use: Blog posts → Featured image or inline content

✅ Quality Checklist

Before Upload:

• [ ] Optimize file sizes (< 2MB for images, < 25MB for videos)
• [ ] Use descriptive filenames (no spaces, use hyphens)
• [ ] Choose correct bucket for content type
• [ ] Organize in appropriate folder

In Keystatic Media Library:

• [ ] Descriptive title (not just filename)
• [ ] Accurate category matching the bucket
• [ ] Alt text for images (accessibility)
• [ ] Tags for organization (optional but helpful)
• [ ] Status set to Published

After Publishing:

• [ ] Test URL accessibility (open in browser)
• [ ] Verify in content (check page/post displays correctly)
• [ ] Mobile-friendly (responsive display)

🚨 Quick Troubleshooting

File Won't Upload:

• ✅ Check file size (see bucket limits above)
• ✅ Verify file format is supported
• ✅ Try smaller file first
• ✅ Refresh browser and retry

URL Not Working:

• ✅ Ensure bucket is public (all current buckets are)
• ✅ Copy exact URL from Supabase console
• ✅ Check for typos in URL
• ✅ Test URL directly in browser

Media Not Showing in Keystatic:

• ✅ Verify Media Library entry was saved
• ✅ Check that status is "Published"
• ✅ Refresh Keystatic admin interface
• ✅ Ensure URL field is populated

Need Help:

• 📖 Full Technical Guide: See Media Management Guide
• 🛠️ CLI Tools: Run pnpm media:help for commands
• 🔍 Debug: Run node scripts/debug-env.mjs for diagnostics

🎯 Examples by Use Case

Content Creator Adding Blog Image:

1. Supabase Console → media_library → Upload to blog/
2. Copy URL: https://project.supabase.co/storage/v1/object/public/media_library/blog/article-hero.jpg
3. Keystatic → Media Library → New entry → Paste URL
4. Blog Post → Featured Image → Select from dropdown

Marketing Team Adding Brochure:

1. Supabase Console → marketing_media → Upload to brochures/
2. Copy URL: https://project.supabase.co/storage/v1/object/public/marketing_media/brochures/product-catalog-2024.pdf
3. Keystatic → Media Library → New entry → Paste URL
4. Marketing Page → Download Link → Select from dropdown

Developer Bulk Upload:

# Upload product photos
node scripts/bulk-media-upload.mjs \
  --bucket=website_media \
  --folder=./product-photos \
  --destination=products/tactical-gear/ \
  --filter=jpg,png,webp

# URLs automatically output for Keystatic entry creation

This quickstart covers 90% of daily media operations. For advanced scenarios, refer to the complete technical guide.