Skip to main content

Supabase Storage

Supabase Storage lets you upload files, images, and documents. Perfect for user avatars, photo uploads, and any file your app needs to store.

Prerequisites


Storage Concepts

Buckets

Buckets are containers for your files — like folders at the top level. Examples:
  • avatars — User profile photos
  • uploads — User-uploaded content
  • documents — PDFs and files

Objects

Objects are the actual files inside buckets. Each has:
  • A unique path (e.g., avatars/user123.jpg)
  • Metadata (size, type, etc.)
  • Access permissions

Creating a Bucket

In Supabase Dashboard

  1. Go to Storage in sidebar
  2. Click Create a new bucket
  3. Name it (e.g., avatars)
  4. Choose public or private

Public vs Private


Uploading Files

Basic Upload

Ask Nativeline:

Upload Code Pattern


Organizing Files

By User

By Content Type


Getting File URLs

Public Buckets

Private Buckets


Downloading Files


Deleting Files


Storage Security

Bucket Policies

Like RLS for database, set policies for storage: Allow users to upload to their own folder:
Allow anyone to view public avatars:

Setting Policies in Dashboard

  1. Storage → Select bucket
  2. Policies tab
  3. Add new policy
  4. Choose template or write custom

Common Use Cases

Profile Photo Upload

Document Upload


File Size and Types

Limits

  • Default max file size: 50 MB
  • Can be increased in settings

Accepted Types

By default, all types are accepted. You can restrict in bucket settings.

Compression


Best Practices

Large images use storage and bandwidth. Compress and resize before uploading.
Include user ID and timestamp to avoid conflicts: user-123/1704067200-photo.jpg
Private buckets need policies. Public buckets are open — use carefully.
Show progress, handle errors gracefully, allow retry.

Troubleshooting

  • Check bucket exists
  • Verify policies allow upload
  • Check file size limits
  • Ensure user is authenticated (for private buckets)
  • Public bucket? Use getPublicURL
  • Private bucket? Use createSignedURL
  • Check RLS policies
  • Compress images before upload
  • Use appropriate quality settings
  • Check network connection

Next Steps

Realtime

Live updates when data changes

Database

Store file metadata in tables