Melhores bibliotecas JavaScript de upload de arquivos: Uppy vs FilePond vs Dropzone

Comece pelo contrato de upload, não pela área de soltar arquivos

As três bibliotecas conseguem deixar um campo de arquivo com aparência moderna. Essa é a parte menos cara de um upload em produção. Primeiro, decida para onde vão os bytes, qual protocolo o receptor usa, quando um upload passa a ser durável e qual identificador conecta o progresso no navegador a um registro da aplicação. Um upload direto para armazenamento de objetos, um servidor tus, um endpoint multipart convencional e um serviço de processamento têm contratos de autorização e de conclusão diferentes, mesmo quando a interface parece idêntica.

Esta comparação seleciona três bibliotecas de upload independentes para navegador que oferecem componentes de interface e documentam um contrato de servidor. Defina a recuperação com precisão. “Suporta blocos” pode significar apenas que uma única sessão de página consegue tentar novamente o envio de um bloco que falhou. Um fluxo retomável precisa manter uma identidade de upload emitida pelo servidor, descobrir o offset aceito e continuar com segurança depois que o cliente perde o estado. Defina também cancelamento, expiração, requisições finais duplicadas e o que a interface mostra quando a transferência termina, mas a validação ou o processamento assíncrono falhou.

Use o Uppy para fluxos modulares e infraestrutura retomável

O Uppy separa seu mecanismo de estado dos plugins de interface e de upload. Uma equipe pode usar o Dashboard para um seletor integrado, o DragDrop para uma área menor, o Tus para um endpoint retomável ou o plugin Transloadit para uma Assembly de upload e processamento. Essa composição é valiosa quando um produto precisa de vários tipos de origem ou quando a experiência visível deve mudar sem substituir a camada de transferência.

A contrapartida é a área de superfície da arquitetura. A compatibilidade de plugins, os estilos, o tratamento de eventos e o endpoint escolhido continuam exigindo manutenção. Provedores remotos usam a infraestrutura do Companion em vez de expor credenciais de terceiros no navegador; as equipes podem hospedá-lo por conta própria ou usar o Companion hospedado incluído na Transloadit. O Uppy é uma boa escolha padrão para transferências grandes ou instáveis quando o back-end já usa tus, e é o caminho com manutenção ativa mais curto até a Transloadit, porque o plugin oficial cuida da criação da Assembly e da coordenação do upload.

Use o FilePond para um campo de arquivo refinado e plugins de imagem

O FilePond parte de um elemento input e o transforma em um campo de arquivo compacto e configurável. Seu catálogo de plugins abrange pré-visualização, recorte, redimensionamento, transformação, metadados e validação de imagens, o que o torna atraente para formulários em que os usuários precisam de feedback visual imediato sobre imagens. Adaptadores para frameworks podem ajudar a integrá-lo naturalmente a um sistema de componentes existente, mas o ciclo de vida no servidor continua sendo um contrato do FilePond.

Esse contrato é explícito. Sem envio em blocos, process aceita um arquivo e retorna um identificador de arquivo no servidor; revert remove um upload temporário; restore recupera um arquivo temporário interrompido ou enviado anteriormente. Com envio em blocos, o POST inicial de process não carrega nenhum arquivo e retorna um identificador de transferência; em seguida, o FilePond envia requisições PATCH com os blocos e requisições HEAD de recuperação para o endpoint patch configurado. Esse pode ser um bom design quando a aplicação controla ambos os lados. Ele não é intercambiável com tus só porque ambos os designs enviam blocos e usam requisições HEAD.

Use o Dropzone para um fluxo XHR convencional de arrastar e soltar

O Dropzone transforma um elemento HTML em uma área de upload de arrastar e soltar, fornece pré-visualizações e progresso e envia arquivos via XMLHttpRequest. Sua configuração é direta, e uma equipe com um endpoint de aplicação convencional consegue chegar rapidamente a uma experiência funcional. Envio opcional em blocos, blocos paralelos, limites de novas tentativas, geração de miniaturas e redimensionamento de imagens no lado do cliente ampliam esse caminho sem exigir um framework de interface separado.

Boa parte do significado fica a cargo do back-end. Ele precisa interpretar os campos de bloco do Dropzone, armazenar dados parciais com segurança, montar cada arquivo exatamente uma vez e distinguir uma nova tentativa de um segundo upload. A recuperação após navegação ou reinício do navegador não fica garantida só por ativar o envio em blocos. Na data de publicação, a tag latest do Dropzone no npm é 6.0.0-beta.2, enquanto a última linha estável é 5.9.3; o exemplo usa a exportação ESM nomeada do beta 6. Fixe a linha pretendida e teste o formato de importação em vez de copiar a configuração entre versões.

Compare as três nas mesmas dimensões

Em arquitetura de transferência, o Uppy tem o caminho orientado a protocolo mais claro, por meio do plugin Tus, e um caminho direto para processamento, por meio do plugin Transloadit. O FilePond tem um ciclo de vida documentado no servidor da aplicação, com operações de arquivos temporários e um protocolo opcional de blocos. O Dropzone usa uploads XHR comuns e acrescenta metadados de blocos e novas tentativas configuráveis. Nenhum desses contratos é intrinsecamente correto para todo back-end.

Quanto ao formato da interface, o FilePond favorece uma experiência compacta de campo de arquivo, o Uppy vai de um estado headless até um Dashboard completo, e o Dropzone gira em torno de um elemento que se torna uma área para soltar arquivos com pré-visualizações. Em fluxos de trabalho com imagens, o FilePond oferece um amplo conjunto de plugins de imagem específicos; o Uppy e o Dropzone também oferecem pré-visualização ou miniaturas, mas não devem ser escolhidos como processadores de mídia autoritativos. Em portabilidade, prefira um protocolo de comunicação aberto quando for importante trocar o cliente ou o servidor de forma independente.

Prototipe cada biblioteca com um contrato de servidor real

Estas configurações apontam intencionalmente para três contratos de endpoint diferentes. O exemplo do Uppy precisa de um servidor tus. O exemplo do FilePond precisa de handlers process, patch, revert e restore que implementem a semântica de blocos dele. O exemplo do Dropzone precisa de um endpoint que entenda e monte blocos do Dropzone. Trocar o nome do pacote mantendo a mesma URL não torna o servidor compatível.

Os limites numéricos também não são intercambiáveis, de propósito: o maxFileSize do Uppy é expresso em bytes, enquanto o maxFilesize do Dropzone é expresso em mebibytes (MiB). O exemplo do FilePond omite um plugin de tamanho para manter o foco no ciclo de vida no servidor; o código de produção precisa adicionar e aplicar um limite adequado tanto no cliente quanto no servidor.

Use os exemplos como estrutura para experimentos, não como autorização de produção. Emita permissões de upload de curta duração a partir de um servidor confiável, associe-as ao usuário e à operação atuais, aplique limites de bytes e de quantidade no receptor e retorne um identificador opaco que a aplicação possa reconciliar. Remova os logs de console antes de publicar e renderize os erros em uma região de status acessível perto do controle de upload.

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Tus from '@uppy/tus'

import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'

const uppy = new Uppy({
  restrictions: {
    allowedFileTypes: ['image/*', 'video/*'],
    maxFileSize: 500 * 1024 * 1024,
    maxNumberOfFiles: 10,
  },
})
  .use(Dashboard, {
    inline: true,
    target: '#uppy',
  })
  .use(Tus, {
    endpoint: 'https://uploads.example.com/files/',
    retryDelays: [0, 1_000, 3_000, 5_000],
  })

uppy.on('complete', ({ successful }) => {
  console.log('Uploaded files:', successful)
})

import { create, registerPlugin } from 'filepond'
import FilePondPluginFileValidateType from 'filepond-plugin-file-validate-type'
import FilePondPluginImagePreview from 'filepond-plugin-image-preview'

import 'filepond/dist/filepond.min.css'
import 'filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css'

registerPlugin(FilePondPluginFileValidateType, FilePondPluginImagePreview)

const input = document.querySelector('input[type="file"]')

if (!(input instanceof HTMLInputElement)) {
  throw new Error('Missing file input')
}

create(input, {
  acceptedFileTypes: ['image/*'],
  chunkSize: 5_000_000,
  chunkUploads: true,
  server: {
    process: '/api/filepond/process',
    patch: '/api/filepond/patch/',
    revert: '/api/filepond/revert',
    restore: '/api/filepond/restore/',
  },
})

import { Dropzone } from 'dropzone'

const dropzone = new Dropzone('#dropzone', {
  acceptedFiles: 'image/*,video/*',
  chunkSize: 2_000_000,
  chunking: true,
  forceChunking: true,
  maxFilesize: 500,
  retryChunks: true,
  retryChunksLimit: 3,
  url: '/api/dropzone/upload',
})

dropzone.on('success', (file, response) => {
  console.log('Upload accepted:', file.name, response)
})

dropzone.on('error', (file, message) => {
  console.error('Upload failed:', file.name, message)
})

Teste o comportamento em falhas antes de escolher a vencedora

Submeta todas as candidatas aos mesmos dados de teste e às mesmas falhas: uma imagem minúscula, um vídeo grande, um arquivo com zero bytes, uma extensão enganosa, uma conexão interrompida, um recarregamento de página, uma autorização expirada, uma requisição final duplicada, um cancelamento pelo usuário e uma rejeição do servidor depois que todos os bytes chegam. Meça os bytes retransmitidos, o tempo de recuperação, o trabalho duplicado no servidor, o vazamento de arquivos temporários e se o usuário consegue entender o estado.

Em seguida, teste a divisão de responsabilidades da integração. Verifique o acesso por teclado, a movimentação do foco, os anúncios de erro, a localização, o uso de memória em dispositivos móveis, o comportamento do framework ao desmontar componentes, as atualizações de dependências e a observabilidade do endpoint. A decisão deve registrar a linha de versão, os plugins selecionados, o protocolo do servidor, o responsável pelo estado dos ativos e o plano de substituição. Esse registro importa mais do que um ranking genérico porque explica por que a escolha continua adequada depois que o desenvolvedor original sai.