Criando uma experiência de upload fluida com o Uppy
Uploads de arquivos são um componente essencial das aplicações web modernas. Este DevTip mostra como criar uma experiência de upload eficiente e fácil de usar com o Uppy, um poderoso uploader de arquivos em JavaScript.
Introdução
Lidar com uploads de arquivos em aplicações web exige equilíbrio entre experiência do usuário, desempenho e segurança. O Uppy é um uploader de arquivos modular em JavaScript que se destaca em todas essas áreas e oferece uma solução robusta para gerenciar uploads de arquivos no navegador.
Quais ferramentas são populares para lidar com uploads no navegador?
O Uppy se destaca no ecossistema de upload de arquivos por sua arquitetura moderna, seu amplo conjunto de recursos e sua excelente experiência para desenvolvedores. Ele oferece uma solução completa que inclui:
- Funcionalidade de arrastar e soltar
- Indicadores de progresso
- Pré-visualização de arquivos
- Suporte a uploads retomáveis
- Integrações com provedores remotos
Configurando o Uppy em um ambiente de navegador
Você pode instalar o Uppy usando o npm:
npm install @uppy/core @uppy/dashboard @uppy/xhr-upload
Em aplicações baseadas em módulos, importe e inicialize o Uppy assim:
import { Uppy } from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import XHRUpload from '@uppy/xhr-upload'
import '@uppy/core/css/style.min.css'
import '@uppy/dashboard/css/style.min.css'
const uppy = new Uppy().use(Dashboard, {
inline: true,
target: '#drag-drop-area',
}).use(XHRUpload, { endpoint: '/upload', fieldName: 'file' })
Como alternativa, use a CDN para protótipos rápidos:
<link href="https://releases.transloadit.com/uppy/v4.13.1/uppy.min.css" rel="stylesheet" />
<script type="module">
import { Uppy, Dashboard, XHRUpload } from 'https://releases.transloadit.com/uppy/v4.13.1/uppy.min.mjs'
</script>
Implementando um recurso básico de upload
Crie uma interface básica de upload com o Uppy:
<div id="drag-drop-area"></div>
Use esta inicialização no lugar da anterior para adicionar manipuladores de eventos. O endpoint
/upload precisa aceitar requisições POST multipart com um campo file e retornar uma resposta
JSON de sucesso. O XHRUpload, por si só, não oferece uploads retomáveis nem em partes; para isso, use
o plugin Tus.
const uppy = new Uppy()
.use(Dashboard, {
inline: true,
target: '#drag-drop-area',
})
.use(XHRUpload, { endpoint: '/upload', fieldName: 'file' })
.on('upload-success', (file, response) => {
console.log(`${file.name} uploaded successfully`)
})
.on('upload-error', (file, error) => {
console.error(`Error uploading ${file.name}:`, error)
})
uppy.on('complete', (result) => {
console.log('Upload complete! Files:', result.successful)
})
Recursos e funcionalidades modernos
O Uppy evolui continuamente para atender às demandas do desenvolvimento web moderno. O Uppy 4.x traz vários recursos poderosos:
- Suporte nativo a TypeScript para mais segurança de tipos
- Integração com React Hooks para incorporar o Uppy facilmente em aplicações React
- Um editor de imagens integrado para ajustes na hora
- Integração com o Google Fotos para selecionar arquivos remotos com facilidade
- Tratamento de erros aprimorado e mecanismos de nova tentativa configuráveis
Boas práticas de segurança
Garanta uma segurança robusta configurando tanto o cliente quanto o servidor para validar e proteger os uploads de arquivos. No lado do cliente, aplique restrições para minimizar os riscos:
uppy.setOptions({
restrictions: {
maxFileSize: 2 * 1024 * 1024, // 2MB
allowedFileTypes: ['image/*', '.pdf'],
maxNumberOfFiles: 5,
},
})
Em um servidor Express existente, instale o cors com npm install cors e configure-o para a origem do
seu frontend. O CORS não substitui autenticação, autorização nem validação no lado do servidor.
const cors = require('cors')
app.use(
cors({
origin: 'https://your-domain.com',
methods: ['POST'],
allowedHeaders: ['Content-Type', 'Authorization'],
}),
)
O helper em JavaScript a seguir ilustra verificações de metadados em um handler Express/Multer existente. Trate os tipos MIME como não confiáveis, valide o conteúdo dos arquivos antes de usá-los e aplique limites de tamanho durante o recebimento dos dados, não apenas depois que o upload terminar:
const validateFile = (file) => {
const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf']
if (!allowedTypes.includes(file.mimetype)) {
throw new Error('Invalid file type')
}
if (file.size > 2 * 1024 * 1024) {
throw new Error('File too large')
}
}
Solução de problemas comuns
Configuração de CORS
Reutilize o middleware de CORS acima com a origem real do seu frontend. Não substitua a origem explícita por um curinga. CORS não é autenticação; autorize as requisições de upload de forma independente.
Erros de rede
O Dashboard pode tentar novamente os uploads que falharam. Para um botão personalizado de nova
tentativa, chame retryAll() na instância existente dentro do handler de clique:
await uppy.retryAll()
Validação de tipo de arquivo
Trate as restrições de tipo de arquivo de forma amigável e clara, mantendo os usuários informados sobre os problemas:
uppy.on('restriction-failed', (file, error) => {
console.error(error)
// Display a user-friendly error message
showErrorNotification(`${file.name}: ${error.message}`)
})
Dicas de otimização de desempenho
Melhore o desempenho e a experiência do usuário seguindo estas dicas:
- Escolha o plugin Tus e um endpoint compatível com tus quando arquivos grandes exigirem uploads retomáveis
- Implemente um tratamento de erros adequado e mecanismos de nova tentativa
- Use compressão quando fizer sentido
- Monitore o progresso do upload e dê feedback em tempo real
const uppy = new Uppy({
autoProceed: true,
allowMultipleUploadBatches: true,
debug: process.env.NODE_ENV === 'development',
})
uppy.on('upload-progress', (file, progress) => {
const percent = (progress.bytesUploaded / progress.bytesTotal) * 100
updateProgressBar(percent)
})
Conclusão
O Uppy oferece uma solução robusta para lidar com uploads de arquivos em aplicações web modernas. Seu amplo conjunto de recursos, seus sólidos recursos de segurança e sua excelente experiência para desenvolvedores fazem dele uma escolha ideal para integrar uploads de arquivos aos seus projetos.
Para soluções avançadas de processamento e armazenamento de arquivos, vale a pena conhecer o serviço de uploads de arquivos da Transloadit e o Uppy.