Static images committed to a git repo work fine — until they don’t. Once a marketing site has 200+ photos, your repo size balloons, your Coolify build slows down to copy the assets, and you can’t update an image without a redeploy. Supabase Storage solves all three. Here’s the bucket layout, the access posture, and the helper that make it ergonomic across a client book, from the setup we ran at FH before moving to a shared CMS media library.
Why Storage beats /public for media
- Git repo stays small. Marketing photos do not belong in version control.
- Image updates don’t require a redeploy. Upload a new file to the bucket and it’s live (with next/image caching headers respecting the change).
- CDN-backed delivery. Supabase Storage is fronted by a CDN already; pair it with Cloudflare and you have two layers of caching.
- Per-tenant isolation. Different buckets for different clients, with RLS-scoped access if you need it.
The bucket layout we used across FH
One public bucket per client (`client-a-images`, `client-b-images`). Each bucket was public-read for anon, write for service-role only. Inside the bucket, paths mirrored the site’s information architecture: `home/hero.jpg`, `team/john.avif`, `portfolio/client-a/exterior-1.jpg`, `blog/seo-cost/cover.jpg`.
We didn’t version the path. If we replaced `home/hero.jpg` with a new image, the URL didn’t change. CDN cache invalidation was handled by the deploy script or, in practice, by the next/image cache TTL expiring.
Bucket creation and policies
Create the bucket in the Supabase dashboard, mark it public, then write the RLS policy for write access. Anon read is automatic on public buckets.
-- Storage RLS policy: only service-role can upload
create policy "service-role uploads" on storage.objects
for insert
with check (auth.jwt() ->> 'role' = 'service_role');
create policy "service-role updates" on storage.objects
for update
using (auth.jwt() ->> 'role' = 'service_role');
create policy "service-role deletes" on storage.objects
for delete
using (auth.jwt() ->> 'role' = 'service_role');Uploading: the script workflow
Don’t upload production assets through the dashboard. Use a small Node script that takes a local file, runs it through Sharp to resize and convert to multiple formats (AVIF, WebP, original), then uploads each variant to the bucket. Have the script write a `meta.json` alongside each asset with license, source, intended channel, and the curation score from the intake-image flow.
import { createClient } from "@supabase/supabase-js";
import sharp from "sharp";
import { readFile } from "node:fs/promises";
const admin = createClient(
process.env.SUPABASE_URL!,
process.env.SUPABASE_SERVICE_ROLE_KEY!
);
async function uploadHero(localPath: string, bucketPath: string, bucket: string) {
const buffer = await readFile(localPath);
const resized = await sharp(buffer)
.resize({ width: 2400, withoutEnlargement: true })
.jpeg({ quality: 88 })
.toBuffer();
await admin.storage.from(bucket).upload(bucketPath, resized, {
contentType: "image/jpeg",
cacheControl: "public, max-age=31536000, immutable",
upsert: true,
});
}Resolving URLs: the imageUrl() helper
Give every site a `lib/storage.ts` with an `imageUrl()` function that resolves a bucket-relative path into a fully-qualified Supabase URL. Pass it a path; get back a URL. The bucket defaults to the per-site bucket but can be overridden for shared components that pull images from multiple tenant buckets.
// lib/storage.ts
const FALLBACK = "https://your-project-id.supabase.co";
const URL = process.env.NEXT_PUBLIC_SUPABASE_URL ?? FALLBACK;
export const DEFAULT_BUCKET = "fh-images";
export function imageUrl(path: string, opts: { bucket?: string } = {}) {
const bucket = opts.bucket ?? DEFAULT_BUCKET;
const cleaned = path.replace(/^\/+/, "");
return `${URL}/storage/v1/object/public/${bucket}/${cleaned}`;
}Cache headers
Supabase Storage respects the `cacheControl` you set on upload. Default to `public, max-age=31536000, immutable` for any image whose URL won’t change. If the URL might change (a header that gets re-uploaded with the same name during a site refresh), drop the `immutable` and lower max-age — otherwise CDN intermediaries will hold the old version for a year.
Private buckets for sensitive media
For client-portal documents, signed-URL gated photos, or anything that shouldn’t be world-readable, use a private bucket with RLS policies on `storage.objects`. The client SDK requests a signed URL with `createSignedUrl(path, expiresIn)`, the URL is valid for the requested duration, and outside that window the asset is unreachable.
const { data, error } = await supabase
.storage
.from("bhr-private")
.createSignedUrl("contracts/2026-q2-statement.pdf", 600);
// data.signedUrl is valid for 10 minutesAsset curation: meta.json sidecar
Give every image a sibling `meta.json` with the source, license, prompt or camera details, intended channel, and a 0–10 score per the FH curation rubric. The rubric blocks AI-slop tells (melted hands, six-fingered hands, plastic skin) and stock-photo cliches (handshake, generic team-around-laptop). Curation gates can run automatically when a file lands in the bucket’s inbox prefix.
Bandwidth math at scale
Supabase Pro includes 250GB egress per month. At an average optimized hero of 60KB, that covers roughly 4M hero loads per month across all clients. If you exceed it, overage is $0.09/GB. Even at 4× the included egress, the bill is $90 — still cheaper than ten separate CMSs charging $40 each.
Migrating from /public to Supabase Storage
We’ve done this migration on three legacy client sites. The pattern: (1) script that uploads every file in `/public/images/` to the appropriate bucket; (2) global find-and-replace from `/images/...` to `imageUrl("...")`; (3) verify with a build that no `/images/` references remain; (4) deploy. Total time on a 200-asset site: 90 minutes.
Where we run this now
FH client sites read images from Supabase Storage today, but no longer through a bucket per client and an `imageUrl()` helper. We moved to one media library in our CMS: photos are uploaded once, converted to WebP, resized into a fixed set of variants, and served directly to the page. The bucket-per-tenant pattern is still what we’d suggest for a team with no CMS in front of storage. If your site is committing 300MB of marketing images to git on every deploy, book a consultation and we’ll help you get them out.
