Como Fazer Upload de Arquivos no Supabase Storage

Fazer upload de arquivos no Supabase Storage exige escolher o metodo certo conforme o tamanho do arquivo: uploads padrao para arquivos de ate 6MB, e TUS Resumable Upload para arquivos maiores, com controle de acesso via Row Level Security. O Supabase Storage funciona como um sistema de arquivos completo integrado ao banco Postgres, com CDN global e otimizacao automatica de imagens.

Se voce desenvolve aplicacoes com React, Vite e Supabase (como e comum em projetos de agencias digitais), entender bem o Storage evita retrabalho e problemas de performance la na frente.

##O que e o Supabase Storage

O Supabase Storage e o servico de armazenamento de arquivos do Supabase, pensado para guardar imagens, videos, PDFs e qualquer tipo de arquivo binario fora do banco de dados relacional. Ele organiza os arquivos em "buckets" (como pastas de nivel superior), cada um com suas proprias regras de acesso.

Existem tres tipos principais de buckets: buckets de arquivo tradicionais (para uploads gerais), buckets de analytics em formato Iceberg (para data lakes) e buckets de vetores voltados para embeddings de inteligencia artificial com busca por similaridade. Para a maioria dos sites e sistemas, o bucket de arquivo tradicional e o que resolve o problema.

##Como fazer upload de arquivos no Supabase Storage

O metodo mais simples e usar o SDK supabase-js, chamando from('nome-do-bucket').upload() com o caminho do arquivo e o conteudo binario. Esse fluxo padrao funciona bem para:

1. Fotos de perfil de usuarios
2. Imagens de produtos em e-commerce
3. Documentos e comprovantes enviados por clientes
4. Arquivos de mídia em sistemas internos

O metodo padrao de upload e recomendado para arquivos de ate 6MB. Antes de liberar o upload no front-end, sempre valide tipo e tamanho do arquivo no client e reforce essas regras no bucket, para evitar abuso.

###Buckets publicos ou privados

Um bucket pode ser publico (qualquer pessoa com a URL acessa o arquivo) ou privado (acesso controlado por politicas). Para arquivos sensiveis, como documentos fiscais ou contratos, o bucket privado com Row Level Security e a escolha correta.

##Upload de arquivos grandes: quando usar TUS

Para arquivos maiores que 6MB, a recomendacao oficial e usar o protocolo TUS Resumable Upload, que permite retomar o envio caso a conexao caia no meio do processo. Isso e essencial para videos, arquivos de design ou backups enviados por usuarios com conexao instavel.

O Supabase tambem oferece compatibilidade com o protocolo S3, o que facilita a migracao de projetos que ja usam ferramentas do ecossistema AWS para lidar com uploads e integrações de terceiros.

##Segurança no upload de arquivos: Row Level Security

Sem politicas de Row Level Security (RLS) bem configuradas, qualquer usuario autenticado pode acabar lendo ou sobrescrevendo arquivos de outras pessoas. As boas praticas incluem:

• Definir políticas de INSERT, SELECT, UPDATE e DELETE separadas por bucket
• Restringir uploads por pasta do usuario (ex: usar o ID do usuario no caminho do arquivo)
• Nunca expor a service_role key no front-end
• Validar o tipo MIME do arquivo tanto no client quanto via política no servidor

Essas regras evitam que o Storage vire uma porta aberta para uso indevido do espaço de armazenamento e, principalmente, para vazamento de dados.

##CDN e otimização de imagens

O Supabase Storage entrega arquivos através de uma CDN global, o que reduz o tempo de carregamento para usuários em diferentes regiões. Para imagens, também é possível usar a transformação de imagens on the fly, redimensionando e comprimindo arquivos direto pela URL, sem precisar gerar múltiplas versões manualmente no upload.

##Perguntas Frequentes

Qual o tamanho máximo de arquivo no Supabase Storage? No método padrão, o limite recomendado é de 6MB para maior confiabilidade, mas tecnicamente é possível enviar até 5GB. Para arquivos grandes, o ideal é usar TUS Resumable Upload.

Supabase Storage é seguro para guardar documentos de clientes? Sim, desde que o bucket seja privado e existam políticas de Row Level Security bem definidas, restringindo o acesso a cada arquivo pelo dono do registro.

Preciso pagar para usar o Supabase Storage? O Supabase tem um plano gratuito com limite de armazenamento, adequado para projetos pequenos e MVPs. Projetos maiores costumam migrar para planos pagos conforme o volume de arquivos cresce.

Dá para usar o Supabase Storage com React e Vite? Sim, o SDK supabase-js funciona normalmente em projetos React com Vite, bastando inicializar o client com a URL e a chave anon do projeto e chamar os métodos de upload do Storage.

Qual a diferença entre bucket público e privado? Bucket público expõe o arquivo para qualquer pessoa com a URL, enquanto o privado exige autenticação e políticas de acesso para liberar a leitura ou o download.

Configurar o Storage corretamente desde o início evita retrabalho e riscos de segurança mais à frente. Para quem não tem tempo ou equipe técnica para cuidar dessa parte, a Stormcore desenvolve sites, sistemas e integrações com Supabase já com as políticas de acesso e upload configuradas do jeito certo.