Saltar al contenido principal

Comenzando con Dropup

Dropup es una biblioteca React ligera y sin interfaz para carga de archivos que te da control total sobre tu interfaz mientras maneja toda la lógica compleja de carga.

¿Por qué Dropup?​

  • 🪶 Ligero - El núcleo es solo ~10KB comprimido
  • 🎨 Sin interfaz - Control total sobre tu UI con API basada en hooks
  • 📁 Arrastrar y soltar - Soporte integrado para arrastrar y soltar
  • 📊 Seguimiento de progreso - Progreso de carga en tiempo real para cada archivo
  • 🔄 Cargas fragmentadas - Divide archivos grandes para cargas confiables
  • ☁️ Listo para la nube - Helpers preconfigurados para S3, GCS y Azure
  • 🖼️ Procesamiento de imágenes - Compresión y generación de vistas previas integradas
  • 📱 Multiplataforma - Funciona con React DOM y React Native
  • 🔒 TypeScript - Soporte completo de TypeScript

Instalación​

Instala Dropup usando tu gestor de paquetes preferido:

npm install @samithahansaka/dropup

Dependencias de pares​

Dropup requiere React 16.8 o superior (para soporte de hooks):

npm install react

Inicio rápido​

Aquí hay un ejemplo simple para comenzar:

import { useDropup } from '@samithahansaka/dropup';

function FileUploader() {
  const {
    files,
    state,
    actions,
    getDropProps,
    getInputProps
  } = useDropup({
    accept: 'image/*',
    maxSize: 10 * 1024 * 1024, // 10MB
    multiple: true,
  });

  return (
    <div>
      {/* Zona de soltar */}
      <div
        {...getDropProps()}
        style={{
          border: state.isDragging ? '2px dashed blue' : '2px dashed gray',
          padding: 40,
          textAlign: 'center',
          cursor: 'pointer',
        }}
      >
        <input {...getInputProps()} />
        <p>Arrastra y suelta archivos aquí, o haz clic para seleccionar</p>
      </div>

      {/* Lista de archivos */}
      <ul>
        {files.map((file) => (
          <li key={file.id}>
            {file.name} - {file.status}
            {file.status === 'uploading' && ` (${file.progress}%)`}
            <button onClick={() => actions.remove(file.id)}>Eliminar</button>
          </li>
        ))}
      </ul>

      {/* Botón de carga */}
      {files.length > 0 && (
        <button onClick={() => actions.upload()}>
          Cargar todo
        </button>
      )}
    </div>
  );
}

Conceptos principales​

1. El hook useDropup​

El hook useDropup es el punto de entrada principal. Devuelve todo lo que necesitas para construir tu interfaz de carga de archivos:

const {
  files,           // Array de archivos con estado, progreso, etc.
  state,           // Estado general (isDragging, isUploading, progress)
  actions,         // Métodos para cargar, eliminar, cancelar, reiniciar
  getDropProps,    // Props para tu elemento de zona de soltar
  getInputProps,   // Props para el input de archivo oculto
} = useDropup(options);

2. Objetos de archivo​

Cada archivo en el array files contiene:

{
  id: string;          // Identificador único
  file: File;          // Objeto File original
  name: string;        // Nombre del archivo
  size: number;        // Tamaño del archivo en bytes
  type: string;        // Tipo MIME
  preview?: string;    // URL de vista previa (para imágenes)
  status: 'idle' | 'uploading' | 'complete' | 'error';
  progress: number;    // Progreso de carga (0-100)
  error?: Error;       // Objeto de error si la carga falló
  uploadedUrl?: string; // URL después de carga exitosa
}

3. Acciones​

El objeto actions proporciona métodos para controlar las cargas:

actions.upload(fileIds?)    // Iniciar carga (todos o archivos específicos)
actions.cancel(fileId?)     // Cancelar carga(s)
actions.remove(fileId)      // Eliminar un archivo de la lista
actions.reset()             // Limpiar todos los archivos
actions.retry(fileIds?)     // Reintentar cargas fallidas

Configurando cargas​

Para habilitar cargas reales, proporciona una configuración de carga:

const { files } = useDropup({
  upload: {
    url: '/api/upload',
    method: 'POST',
    headers: {
      'Authorization': 'Bearer token',
    },
  },
  autoUpload: true, // Cargar automáticamente cuando se agregan archivos
});

Próximos pasos​