Next.js boilerplate with Supabase Storage

Every bucket is created by a migration

• Buckets, their public flag, their file_size_limit, their allowed_mime_types and every policy on storage.objects live in supabase/migrations/. A bucket created in the dashboard exists in exactly one project: not in a teammate's local stack, not in a preview branch, not in the environment you promote to next month.
• The first symptom of a hand-made bucket is "works on my machine". The second is a production bucket whose policies nobody can review, because they were never written down.
• Use on conflict (id) do update so applying the migration twice converges rather than failing. A storage migration should be safe to re-run against a project where the bucket already exists.
• Changing the bucket name means changing it in the migration and in SUPABASE_STORAGE_BUCKET. They are two halves of one decision.

Private by default

• New buckets are private. A public bucket serves every object to anyone who can guess a key, forever, with no way to revoke: that is a product decision, not a convenience, and it is made once per bucket.
• Public and private objects never share a bucket. One bucket per access model: uploads (private, user-owned) and, if you need it, public-assets (deliberately public, for things that are public by nature).
• bun run verify fails if the private bucket has been flipped to public. That check exists because the flip is one click in a dashboard and invisible in a diff.

Policies

• storage.objects has row level security on. With no policies, nothing is readable or writable by anon or authenticated roles: the correct default, and the reason every policy below it must be deliberate.
• Policies are written against the key layout <owner-id>/<prefix>/<uuid>-<name>, so (storage.foldername(name))[1] is the owner. Change the key layout and every policy changes with it: they are one design, not two.
• Write the four operations separately (select, insert, update, delete). A single for all policy hides the case where you meant to allow reads but not deletes.
• Wrap auth.uid() in a scalar subselect ((select auth.uid()::text)) so Postgres evaluates it once per statement rather than once per row.
• Never grant anything to anon on a private bucket. If anonymous reads are genuinely needed, that is a different, public bucket.
• Policies are the second line of defence. The service role key used by src/lib/storage/index.ts bypasses all of them, so the authorisation check in src/lib/storage/authorize.ts is the first line, and the one that actually runs for every request this app makes.

Applying and testing

• Apply with bun run db:reset locally and bunx supabase db push against a linked project. Never by pasting SQL into the dashboard's editor.
• Test a policy by acting as a user, not as the service role: sign in as user A and attempt to read a key under user B's prefix. A test that runs with the service role key proves nothing, because the service role ignores policies.

A signed URL is a bearer credential

Whoever holds one can use it: no session, no cookie, no further checks, from any browser, until it expires. Treat it exactly as you would treat a password you just minted.

• Every route that signs anything calls requireUploader(request) from @/lib/storage/authorize first, before it reads the body and before it touches storage. Nothing below that line may run for an anonymous or cross-origin request.
• Authentication is not authorisation. A signed-in user asking for a signed URL to someone else's key is authenticated and must still be refused. For reads and deletes, check isOwnedBy(key, uploader.id) or look the row up in your database.
• Keys are derived on the server from the session: objectKey({ ownerId: uploader.id, ... }). A key supplied in the request body is a request to write wherever the caller likes.
• Keep lifetimes short. Fifteen minutes for a download is generous; Supabase fixes upload URLs at two hours and it cannot be shortened, which is one more reason to treat the URL as sensitive.
• Never log a signed URL, never put one in an analytics property, an error report or a support conversation, and never render one into a page that is cached. cache-control: no-store is set on the signing response for that reason.

Uploads go to storage, never through a route handler

• The browser uploads directly to Supabase with the URL the server signed. A route handler that receives the file body is wrong here for four separate reasons: the platform body limit (a few MB), function time billed for the whole transfer, memory pressure from buffering, and a second full copy of every byte across the network.
• putObject() is for files your own code produces: a generated PDF, a thumbnail, an export. Not for anything a user is sending.
• Progress belongs to the browser. XMLHttpRequest in <FileDropzone /> reports it; fetch still cannot.

Server-only, always

• src/lib/storage/index.ts holds SUPABASE_SERVICE_ROLE_KEY, which bypasses every row level security policy on the project. It must never be imported, transitively or otherwise, from a client component.
• The client is a singleton with persistSession: false. A service client that tries to keep a session in a serverless function is sharing state between requests from different people.
• Never expose a storage helper as a server action that takes a key from the caller without an ownership check. A server action is a public endpoint.

Validate before you sign

• assertUploadable() checks the filename, the content type against the allowlist, and the claimed size. Allowlist, never blocklist.
• The size the browser reports is a claim: it can ask for a 1 KB upload and send 5 GB. The enforcement is the bucket's file_size_limit, set in the migration. Set both: the code check gives a good error message, the bucket check is what actually holds.
• SVG is deliberately not in the allowlist. It is a document format that can execute script, and serving one from your own origin is stored XSS.

Deleting

• Deletes are authorised the same way as reads: prove ownership first. The service role key can delete anything in the bucket, including objects belonging to other users.
• Deleting the row and deleting the object are two operations that can fail independently. Delete the object first, then the row: an orphaned object costs storage, an orphaned row breaks the page.