Files SDK

O que é o Files SDK?

O Files SDK é um SDK de armazenamento unificado que fornece uma única API consistente para interagir com backends de armazenamento de objetos e blobs. Em vez de aprender um SDK diferente para cada provedor de nuvem, você obtém uma interface pequena e honesta que funciona com S3, Cloudflare R2, Google Cloud Storage, Azure Blob e mais de 30 outros provedores. Ele utiliza E/S baseada em padrões web — aceitando File, Blob, ReadableStream, ArrayBuffer e string — e funciona em qualquer lugar onde fetch é suportado, incluindo Node, Bun, Workers e Vercel.

Para quem é indicado

• Desenvolvedores full-stack que precisam trocar de provedores de armazenamento sem reescrever cada chamada de upload e download em sua aplicação.
• Engenheiros de plataforma que constroem sistemas multi-inquilinos ou multirregionais que devem abstrair peculiaridades específicas de provedores por trás de uma única classe.
• Indie hackers e equipes de startups que desejam começar com um adaptador simples de sistema de arquivos e depois migrar para S3 ou R2 sem alterar o código da aplicação.

Principais recursos

Uma API pequena entre provedores

Upload, download, listar, excluir, head, exists, copiar e geração de URL — os mesmos dez métodos funcionam de forma idêntica, seja usando S3, GCS, Azure ou um sistema de arquivos local. Troque seu adaptador e suas chamadas permanecem as mesmas.

E/S baseada em padrões web

O SDK aceita tipos nativos da web como File, Blob e ReadableStream, e também os retorna. Sem wrappers proprietários de stream ou conversões de buffer. Funciona em qualquer runtime que suporte a API fetch — Node, Bun, Cloudflare Workers, Vercel Edge e muito mais.

Saída de emergência via files.raw

Quando você precisa de recursos específicos do provedor, como versionamento, políticas de ciclo de vida, ACLs ou uploads em várias partes, o cliente nativo está sempre a uma propriedade de distância. files.raw é tipado por adaptador, então você obtém autocompletar completo para o SDK subjacente sem sair do seu código.

Erros previsíveis

Cada erro de provedor é normalizado em um único FilesError com uma propriedade code consistente. O erro original é anexado como cause, permitindo que você lide com falhas de forma uniforme enquanto ainda depura com o contexto completo.

O que se destaca

"Uma API pequena entre provedores. Troque seu provedor de armazenamento sem reescrever chamadas."

Essa é a promessa central, e o Files SDK a cumpre sem concessões. Enquanto outras camadas de abstração vazam detalhes específicos do provedor ou forçam você a uma API de menor denominador comum, o Files SDK oferece uma superfície limpa de dez métodos que cobre 95% dos casos de uso — e então entrega o cliente nativo para os 5% restantes. A matriz de compatibilidade mostra exatamente quais métodos funcionam em qual provedor, com ressalvas claras onde o comportamento difere.

Vale a pena conferir se…

Você está cansado de manter código de adaptador para cada provedor de armazenamento que sua aplicação utiliza, ou está planejando migrar de um backend para outro e quer evitar uma reescrita dolorosa. O Files SDK também é uma ótima opção se você está construindo uma biblioteca ou framework que precisa aceitar armazenamento fornecido pelo usuário sem ditar o provedor.