Storage Explorer

The Storage Explorer provides a visual file manager for Supabase Storage. Browse your buckets, upload files, preview images and videos, and link files to database records through the Data Explorer.

Key capabilities:

• Browse files and folders across all accessible buckets
• Upload files with drag-and-drop
• Preview images, videos, and audio inline
• Download, rename, and delete files
• Link files to database records

Accessing Storage Explorer

Navigate to Storage in the sidebar (or go to /assets).

Permission required: Your role needs storage permissions (Data > Storage > Select) for the buckets you want to access. See Storage Permissions below.

Browsing Files

The Storage Explorer works like a standard file manager:

• Click folders to navigate into them
• Use breadcrumbs to navigate back up
• Search files by name
• View file details (size, type, modified date)

File Details

Click any file to view its details:

The detail panel shows:

• File name and extension
• File size
• Last modified date
• MIME type
• Public URL (for public buckets)

Available actions:

• Download: Download the file to your computer
• Rename: Change the file name
• Delete: Permanently remove the file

Uploading Files

Click Upload Files or drag files directly into the browser window.

Upload behavior:

• Files upload to the current folder
• Existing files with the same name are overwritten (no versioning)
• Upload progress is shown for large files
• Multiple files can be uploaded simultaneously

Creating Folders

Supabase Storage uses virtual folders based on path prefixes. To create a folder:

1. Upload a file with a path prefix (e.g., newfolder/file.txt)
2. The folder appears automatically

Alternatively, some operations allow you to specify a path when uploading.

Linking Files to Records

Storage files can be linked to database records through columns configured as storage types (Image, File, Video, Audio).

In the Data Explorer

When editing a record with a storage column:

Three options:

1. Upload new file: Upload directly from your computer
2. Pick existing file: Browse Storage Explorer and select a file
3. Enter URL manually: Paste an external URL

Picking Files

When you choose to pick an existing file:

Select a bucket, then browse to find your file:

Click the file to select it and link it to the record.

Storage Permissions

Storage access is controlled by data permissions with the Storage scope.

Permission Patterns

Permissions can be scoped to specific buckets and paths:

# All buckets and paths
*
# All files in avatars bucket
avatars/*
# Files in a specific folder
documents/invoices/*
# Single bucket root only
uploads

Configure storage permissions in Roles and Permissions.

Bucket Configuration

Storage Explorer reads from your existing Supabase Storage buckets. Configure buckets through Supabase Studio:

1. Go to Supabase Dashboard > Storage
2. Create buckets for different file categories (avatars, documents, etc.)
3. Set bucket policies (public or private)
4. Configure allowed file types and size limits

Supamode does not create buckets automatically. Ensure buckets exist before configuring storage columns.

Public vs Private Buckets

Public buckets: Files have permanent public URLs. Anyone with the URL can access the file.

Private buckets: Files require signed URLs with expiration. Supamode generates signed URLs automatically when displaying files.

Consider your security requirements when choosing bucket visibility:

• User avatars: Often public
• Invoices/documents: Usually private
• Uploaded content: Depends on use case

Best Practices

Organize with Folder Prefixes

Use consistent path prefixes to organize files:

avatars/{user_id}/profile.jpg
documents/{account_id}/invoices/{year}/invoice-{id}.pdf
uploads/{date}/original-filename.ext

Set Appropriate Bucket Policies

• Enable RLS on private buckets
• Restrict uploads by file type where needed
• Set reasonable size limits

Clean Up Orphaned Files

Deleting a database record doesn't delete linked storage files. Implement cleanup processes for orphaned files:

• Database triggers that delete storage files on record deletion
• Scheduled jobs to find and remove unlinked files