Cursor rule

1---
2description: Follow these rules when working on file storage.
3globs: 
4---
5# Storage Rules
6 
7Follow these rules when working with Supabase Storage.
8 
9It uses Supabase Storage for file uploads, downloads, and management.
10 
11## General Rules
12 
13- Always use environment variables for bucket names to maintain consistency across environments
14- Never hardcode bucket names in the application code
15- Always handle file size limits and allowed file types at the application level
16- Use the `upsert` method instead of `upload` when you want to replace existing files
17- Always implement proper error handling for storage operations
18- Use content-type headers when uploading files to ensure proper file handling
19 
20## Organization
21 
22### Buckets
23 
24- Name buckets in kebab-case: `user-uploads`, `profile-images`
25- Create separate buckets for different types of files (e.g., `profile-images`, `documents`, `attachments`)
26- Document bucket purposes in a central location
27- Set appropriate bucket policies (public/private) based on access requirements
28- Implement RLS (Row Level Security) policies for buckets that need user-specific access
29- Make sure to let me know instructions for setting up RLS policies on Supabase since you can't do this yourself, including the SQL scripts I need to run in the editor
30 
31### File Structure
32 
33- Organize files in folders based on their purpose and ownership
34- Use predictable, collision-resistant naming patterns
35- Structure: `{bucket}/{userId}/{purpose}/{filename}`
36- Example: `profile-images/123e4567-e89b/avatar/profile.jpg`
37- Include timestamps in filenames when version history is important
38- Example: `documents/123e4567-e89b/contracts/2024-02-13-contract.pdf`
39 
40## Actions
41 
42- When importing storage actions, use `@/actions/storage`
43- Name files like `example-storage-actions.ts`
44- Include Storage at the end of function names `Ex: uploadFile -> uploadFileStorage`
45- Follow the same ActionState pattern as DB actions
46 
47Example of a storage action:
48 
49```ts
50"use server"
51 
52import { createClientComponentClient } from "@supabase/auth-helpers-nextjs"
53import { ActionState } from "@/types"
54 
55export async function uploadFileStorage(
56  bucket: string,
57  path: string,
58  file: File
59): Promise<ActionState<{ path: string }>> {
60  try {
61    const supabase = createClientComponentClient()
62    
63    const { data, error } = await supabase
64      .storage
65      .from(bucket)
66      .upload(path, file, {
67        upsert: false,
68        contentType: file.type
69      })
70 
71    if (error) throw error
72 
73    return {
74      isSuccess: true,
75      message: "File uploaded successfully",
76      data: { path: data.path }
77    }
78  } catch (error) {
79    console.error("Error uploading file:", error)
80    return { isSuccess: false, message: "Failed to upload file" }
81  }
82}
83```
84 
85## File Handling
86 
87### Upload Rules
88 
89- Always validate file size before upload
90- Implement file type validation using both extension and MIME type
91- Generate unique filenames to prevent collisions
92- Set appropriate content-type headers
93- Handle existing files appropriately (error or upsert)
94 
95Example validation:
96 
97```ts
98const MAX_FILE_SIZE = 10 * 1024 * 1024 // 10MB
99const ALLOWED_TYPES = ["image/jpeg", "image/png", "image/webp"]
100 
101function validateFile(file: File): boolean {
102  if (file.size > MAX_FILE_SIZE) {
103    throw new Error("File size exceeds limit")
104  }
105  
106  if (!ALLOWED_TYPES.includes(file.type)) {
107    throw new Error("File type not allowed")
108  }
109  
110  return true
111}
112```
113 
114### Download Rules
115 
116- Always handle missing files gracefully
117- Implement proper error handling for failed downloads
118- Use signed URLs for private files
119 
120### Delete Rules
121 
122- Implement soft deletes when appropriate
123- Clean up related database records when deleting files
124- Handle bulk deletions carefully
125- Verify ownership before deletion
126- Always delete all versions/transforms of a file
127 
128## Security
129 
130### Bucket Policies
131 
132- Make buckets private by default
133- Only make buckets public when absolutely necessary
134- Use RLS policies to restrict access to authorized users
135- Example RLS policy:
136 
137```sql
138CREATE POLICY "Users can only access their own files"
139ON storage.objects
140FOR ALL
141USING (auth.uid()::text = (storage.foldername(name))[1]);
142```
143 
144### Access Control
145 
146- Generate short-lived signed URLs for private files
147- Implement proper CORS policies
148- Use separate buckets for public and private files
149- Never expose internal file paths
150- Validate user permissions before any operation
151 
152## Error Handling
153 
154- Implement specific error types for common storage issues
155- Always provide meaningful error messages
156- Implement retry logic for transient failures
157- Log storage errors separately for monitoring
158 
159## Optimization
160 
161- Implement progressive upload for large files
162- Clean up temporary files and failed uploads
163- Use batch operations when handling multiple files