Supabase Storage uses path prefixes as virtual folders — there are no real folder objects. Organize files by including folder-like segments in the file path when uploading, such as 'user_id/photos/image.png'. Use the user's auth ID as the top-level folder for per-user isolation and combine this with RLS policies on storage.objects that check the first path segment against auth.uid().
Organizing Files with Virtual Folders in Supabase Storage
Unlike traditional file systems, Supabase Storage does not have real directories. Instead, forward slashes in file paths create virtual folder structures. This tutorial shows you how to design effective folder hierarchies, implement user-scoped storage patterns, and write RLS policies that leverage folder paths for security.
Prerequisites
- A Supabase project with at least one storage bucket
- The Supabase JS client installed (@supabase/supabase-js v2+)
- Basic understanding of Row Level Security in Supabase
- An authentication setup with signed-in users
Step-by-step guide
Understand virtual folders in Supabase Storage
Understand virtual folders in Supabase Storage
Supabase Storage is backed by S3-compatible object storage where every file is a flat object with a path-like name. The forward slashes in file names create the appearance of folders. When you upload a file to 'invoices/2024/january/report.pdf', Supabase stores it as a single object with that full path as its name. The Dashboard and list() method present these as nested folders for convenience, but there are no actual folder objects to create or manage. This means you cannot create empty folders — a folder only appears when it contains at least one file.
Expected result: You understand that folders in Supabase Storage are virtual path prefixes, not real directory objects.
Design a user-scoped folder structure
Design a user-scoped folder structure
The most common and secure pattern is to use the authenticated user's ID as the top-level folder. This creates natural isolation between users and maps directly to RLS policies. Below the user ID folder, organize by content type or purpose. For example: '{user_id}/avatars/', '{user_id}/documents/', '{user_id}/photos/'. This structure makes it easy to list all of a user's files, grant access only to their own data, and clean up when a user is deleted.
1// Upload to user-scoped folder structure2const { data: { user } } = await supabase.auth.getUser()3const userId = user?.id45// User's avatar6await supabase.storage7 .from('user-files')8 .upload(`${userId}/avatars/profile.jpg`, avatarFile)910// User's document in a date-based subfolder11const today = new Date().toISOString().split('T')[0]12await supabase.storage13 .from('user-files')14 .upload(`${userId}/documents/${today}/report.pdf`, docFile)Expected result: Files are organized under the user's ID with category-based subfolders.
Write RLS policies that enforce folder-based access
Write RLS policies that enforce folder-based access
The storage.foldername(name) function extracts folder path segments from a file's full path. Use this in RLS policies to ensure users can only access files in their own folder. The function returns an array of folder segments — the first element [1] is the top-level folder. By checking that the first folder segment equals the user's ID, you restrict all operations to the user's own files.
1-- Allow users to upload only to their own folder2create policy "User upload to own folder"3on storage.objects for insert4to authenticated5with check (6 bucket_id = 'user-files'7 and auth.uid()::text = (storage.foldername(name))[1]8);910-- Allow users to read only their own files11create policy "User read own folder"12on storage.objects for select13to authenticated14using (15 bucket_id = 'user-files'16 and auth.uid()::text = (storage.foldername(name))[1]17);1819-- Allow users to delete only their own files20create policy "User delete own folder"21on storage.objects for delete22to authenticated23using (24 bucket_id = 'user-files'25 and auth.uid()::text = (storage.foldername(name))[1]26);Expected result: RLS policies enforce that each user can only access files within their own user ID folder.
Create shared folders with team-based access
Create shared folders with team-based access
For applications where teams share files, use a team or organization ID as the folder prefix instead of the user ID. Write RLS policies that check team membership by joining against a teams or team_members table. This allows multiple users to access the same folder while still preventing access from users outside the team.
1-- Team-based folder access2create policy "Team members can read team files"3on storage.objects for select4to authenticated5using (6 bucket_id = 'team-files'7 and (storage.foldername(name))[1] in (8 select team_id::text9 from team_members10 where user_id = (select auth.uid())11 )12);1314-- Team members can upload to their team folder15create policy "Team members can upload to team folder"16on storage.objects for insert17to authenticated18with check (19 bucket_id = 'team-files'20 and (storage.foldername(name))[1] in (21 select team_id::text22 from team_members23 where user_id = (select auth.uid())24 )25);Expected result: Team members can read and upload files in their team's shared folder.
List and navigate folder contents
List and navigate folder contents
Use the list() method with a folder path to browse the virtual folder structure. Pass the folder path as the first argument. The returned items include both files and subfolders at that level. Subfolders have a null id field. Build a recursive navigator by calling list() on each subfolder as the user clicks into it.
1// List root folders for the current user2const { data: { user } } = await supabase.auth.getUser()34const { data: rootItems } = await supabase.storage5 .from('user-files')6 .list(user?.id)78// Separate folders and files9const folders = rootItems?.filter((item) => item.id === null) || []10const files = rootItems?.filter((item) => item.id !== null) || []1112console.log('Folders:', folders.map((f) => f.name))13console.log('Files:', files.map((f) => f.name))1415// Navigate into a subfolder16const { data: subItems } = await supabase.storage17 .from('user-files')18 .list(`${user?.id}/documents`)Expected result: File and subfolder listings are returned for each folder path, enabling folder navigation.
Complete working example
1import { createClient } from '@supabase/supabase-js'23const supabase = createClient(4 process.env.NEXT_PUBLIC_SUPABASE_URL!,5 process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!6)78// Get the authenticated user's ID for folder scoping9async function getUserId(): Promise<string> {10 const { data: { user }, error } = await supabase.auth.getUser()11 if (error || !user) throw new Error('User not authenticated')12 return user.id13}1415// Upload a file to the user's scoped folder16async function uploadToUserFolder(17 category: string,18 fileName: string,19 file: File20) {21 const userId = await getUserId()22 const path = `${userId}/${category}/${fileName}`2324 const { data, error } = await supabase.storage25 .from('user-files')26 .upload(path, file, { upsert: false })2728 if (error) throw new Error(`Upload failed: ${error.message}`)29 return data.path30}3132// List contents of a user's folder33async function listUserFolder(subfolder?: string) {34 const userId = await getUserId()35 const path = subfolder ? `${userId}/${subfolder}` : userId3637 const { data, error } = await supabase.storage38 .from('user-files')39 .list(path, {40 limit: 100,41 sortBy: { column: 'name', order: 'asc' },42 })4344 if (error) throw new Error(`List failed: ${error.message}`)4546 return {47 folders: data.filter((item) => item.id === null),48 files: data.filter((item) => item.id !== null),49 }50}5152// Move a file by copying then deleting (no native move)53async function moveFile(oldPath: string, newPath: string) {54 const userId = await getUserId()55 const fullOldPath = `${userId}/${oldPath}`56 const fullNewPath = `${userId}/${newPath}`5758 const { data: file } = await supabase.storage59 .from('user-files')60 .download(fullOldPath)6162 if (!file) throw new Error('Source file not found')6364 await supabase.storage.from('user-files').upload(fullNewPath, file)65 await supabase.storage.from('user-files').remove([fullOldPath])66}6768// === Usage ===69const { folders, files } = await listUserFolder('documents')70console.log('Subfolders:', folders.map((f) => f.name))71console.log('Files:', files.map((f) => f.name))Common mistakes when organizing Folders in Supabase Storage
Why it's a problem: Trying to create empty folders before uploading files
How to avoid: Supabase Storage does not support empty folders. Folders are virtual and only appear when they contain at least one file. Just upload files with the desired path and folders appear automatically.
Why it's a problem: Hardcoding user IDs in file paths instead of using auth.uid()
How to avoid: Always derive the user ID from supabase.auth.getUser() at runtime. Hardcoded IDs create security gaps and break when used by different users.
Why it's a problem: Using backslashes instead of forward slashes in folder paths
How to avoid: Supabase Storage uses forward slashes (/) as path separators, matching S3 conventions. Backslashes are treated as part of the file name and will not create folder structure.
Best practices
- Use the authenticated user's UUID as the top-level folder for natural per-user isolation
- Organize subfolders by content category (avatars, documents, photos) for logical grouping
- Write RLS policies that check storage.foldername(name)[1] against auth.uid() for security
- Keep folder nesting shallow — two or three levels deep is usually sufficient
- Use consistent naming conventions for folders (lowercase, hyphens or underscores)
- Never trust client-supplied folder paths without validating them against the authenticated user's ID
- Add date-based subfolders for time-series content to make cleanup and archival easier
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I want to organize files in Supabase Storage with user-specific folders. Each user should have their own top-level folder using their auth ID, with subfolders for 'avatars', 'documents', and 'exports'. Show me the upload code, list code, and the RLS policies needed.
Set up a Supabase Storage bucket called 'user-files' with a user-scoped folder structure. Write RLS policies using storage.foldername() to restrict each user to their own folder. Create helper functions for uploading, listing, and navigating the folder hierarchy.
Frequently asked questions
Can I create an empty folder in Supabase Storage?
No, Supabase Storage uses virtual folders based on file path prefixes. Folders only appear when they contain at least one file. You cannot create a standalone empty folder.
How do I rename a folder?
There is no native rename operation for folders. You need to copy all files from the old path to the new path and then delete the originals. For large folders, do this in batches to avoid timeouts.
What characters are allowed in folder names?
Folder names (path segments) can contain letters, numbers, hyphens, underscores, and periods. Avoid spaces and special characters as they need URL encoding. Stick to lowercase alphanumeric characters with hyphens for consistency.
Is there a limit to folder nesting depth?
There is no hard limit on nesting depth, but the total file path (including all folder segments) must stay within S3's 1024-character key limit. In practice, keep nesting to three or four levels for simplicity.
How does the storage.foldername function work?
storage.foldername(name) takes the file's full path and returns an array of folder segments. For 'user123/documents/report.pdf', it returns {'user123', 'documents'}. The [1] index gets the first folder, [2] the second, and so on.
Can I move files between folders?
Supabase Storage does not have a native move operation. To move a file, download it, upload it to the new path, and then delete the original. The copy() method can also be used with the storage API.
Can RapidDev help design a folder structure for my Supabase project?
Yes, RapidDev can design and implement an optimized folder structure for your Supabase Storage, including user-scoped paths, team sharing patterns, and the necessary RLS policies for secure access.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation