Saltar al contenido principal

Introducción

Sube y gestiona archivos en el almacenamiento en la nube con optimización automática.

🎯 ¿Qué hace este módulo?​

El módulo FileUploading te permite subir, recuperar y eliminar archivos en el almacenamiento en la nube de OneEntry: imágenes, PDFs, videos, documentos y cualquier tipo de archivo con optimización automática y entrega a través de CDN.

Piénsalo como tu gestor de almacenamiento en la nube: subes archivos una vez, y OneEntry los almacena, optimiza las imágenes automáticamente y las entrega rápidamente a través de CDN.

📖 Explicación Simple​

Imagina que estás construyendo una aplicación donde los usuarios pueden:

  • 📸 Subir fotos de perfil - redimensionar y optimizar automáticamente
  • 📄 Subir documentos - almacenar PDFs, DOCs de forma segura
  • 🖼️ Subir imágenes de productos - múltiples imágenes por producto
  • 🎥 Subir videos - almacenar y transmitir contenido de video
  • 📎 Subir archivos adjuntos - cualquier tipo de archivo

En lugar de gestionar tu propio almacenamiento:

  • ✅ Sube archivos a la nube de OneEntry
  • ✅ Optimización automática de imágenes (redimensionar, comprimir)
  • ✅ Entrega rápida a través de CDN en todo el mundo
  • ✅ Organiza por tipo de entidad (producto, usuario, página)
  • ✅ Obtén URLs de descarga al instante
  • ✅ Elimina archivos cuando ya no los necesites

Ejemplo del mundo real:

Sin FileUploading (manual):
- Configurar bucket de AWS S3 ❌
- Configurar CDN ❌
- Escribir código de optimización de imágenes ❌
- Gestionar permisos de archivos ❌
- Generar URLs firmadas ❌

Con FileUploading (automático):
- Subir archivo → Obtener URL de descarga ✅
- Imágenes auto-optimizadas ✅
- Entrega de CDN integrada ✅
- Gestión de archivos fácil ✅

✨ Conceptos Clave​

¿Qué es la Carga de Archivos?​

La carga de archivos es almacenar archivos en el almacenamiento en la nube:

  • Subir - Enviar archivo a la nube de OneEntry
  • Almacenamiento - Archivos almacenados de forma segura en la nube
  • CDN - Entrega rápida desde servidores cercanos a los usuarios
  • Optimización - Imágenes auto-comprimidas y redimensionadas
  • URL - Obtener enlace de descarga permanente

Tipos de Archivos Soportados​

Sube cualquier tipo de archivo:

CategoríaTipos de ArchivosAuto-Optimización
ImágenesJPG, PNG, GIF, WebP, SVGSí (redimensionar, comprimir)
DocumentosPDF, DOC, DOCX, XLS, XLSXNo (almacenados tal cual)
VideosMP4, MOV, AVI, WebMNo (almacenados tal cual)
ArchivosZIP, RAR, TAR, GZNo (almacenados tal cual)
OtrosCualquier tipo de archivoNo (almacenados tal cual)

Optimización de Imágenes​

Al subir imágenes, OneEntry puede:

  • 📐 Redimensionar - Reducir dimensiones (por ejemplo, ancho máximo de 1920px)
  • 🗜️ Comprimir - Reducir el tamaño del archivo (más pequeño, más rápido)
  • 🖼️ Formato - Convertir al formato óptimo (WebP)
  • 📱 Responsivo - Crear múltiples tamaños

Ejemplo:

Original: 5MB, 4000x3000px
↓ (auto-optimizar)
Optimizado: 200KB, 1920x1440px

📋 Lo Que Necesitas Saber​

Parámetros de Carga​

Al subir archivos, puedes especificar:

await FileUploading.upload(file, {
  entity: 'product',     // Tipo de entidad (requerido)
  id: 123,               // ID de entidad (opcional)
  type: 'image',         // Sugerencia de tipo de archivo (opcional)
  width: 1920,           // Ancho máximo para imágenes (opcional)
  height: 1080,          // Altura máxima para imágenes (opcional)
  compress: true         // Comprimir imágenes (opcional)
});

Parámetros explicados:

  • file - El objeto de archivo (desde entrada o arrastrar y soltar)
  • entity - Categoría: product, page, block, user, form, general
  • id - ID de entidad para asociar el archivo (por ejemplo, ID de producto)
  • type - Sugerencia de tipo de archivo (generalmente detectado automáticamente)
  • width - Ancho máximo en píxeles (solo imágenes)
  • height - Altura máxima en píxeles (solo imágenes)
  • compress - Habilitar compresión (solo imágenes)

Respuesta de Carga​

Después de subir, obtienes:

{
  filename: "abc123-photo.jpg",              // Nombre de archivo único
  downloadLink: "https://cdn.../photo.jpg",  // URL de CDN
  size: 204800,                              // Tamaño del archivo (bytes)
}

Campos importantes:

  • downloadLink - Usa esta URL en etiquetas <img>, <a>, <video>
  • filename - Guarda esto para eliminar el archivo más tarde
  • size - Tamaño del archivo en bytes (204800 bytes = 200KB)

Mejores Prácticas para la Organización de Archivos​

Organiza archivos por tipo de entidad

Opciones de Optimización de Imágenes​

Controla cómo se optimizan las imágenes:

OpciónQué HaceEjemplo
widthAncho máximo (mantiene la relación de aspecto)width: 1920
heightAltura máxima (mantiene la relación de aspecto)height: 1080
compressReducir el tamaño del archivocompress: true

La relación de aspecto se conserva:

Original: 4000x3000 (relación 4:3)
Con ancho: 800
Resultado: 800x600 (sigue siendo 4:3)

Eliminación de Archivos​

Siempre proporciona entidad, id y nombre de archivo para eliminar:

await FileUploading.delete({
  entity: 'product',
  id: productId,
  filename: 'abc123-photo.jpg'
});

¿Por qué los tres? Los archivos están organizados por entidad → id → nombre de archivo.

📊 Tabla de Referencia Rápida - Métodos​

MétodoQué HaceCuándo Usar
upload()Subir archivo al almacenamiento en la nubeEl usuario sube imagen, documento
getFile()Obtener información del archivo (tamaño, tipo, URL)Verificar si el archivo existe
delete()Eliminar archivo del almacenamientoEliminar archivos antiguos

❓ Preguntas Comunes (FAQ)​

¿Qué tipos de archivos puedo subir?​

Se admite cualquier tipo de archivo:

  • Imágenes: JPG, PNG, GIF, WebP, SVG, BMP, TIFF
  • Documentos: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT
  • Videos: MP4, MOV, AVI, WebM, MKV
  • Archivos: ZIP, RAR, TAR, GZ
  • Otros: Cualquier tipo de archivo

Solo las imágenes se optimizan automáticamente. Los otros archivos se almacenan tal cual.

¿Cuál es el tamaño máximo de archivo?​

Consulta los límites de tu plan de OneEntry. Típicamente:

  • Plan gratuito: 5MB por archivo
  • Planes de pago: 50MB - 100MB por archivo

Mejor práctica: Optimiza las imágenes antes de subir para reducir el tamaño.

¿Los archivos se almacenan permanentemente?​

Sí, los archivos se almacenan hasta que los elimines manualmente usando FileUploading.delete().

Importante: Limpia los archivos no utilizados para ahorrar espacio de almacenamiento.

¿Puedo subir archivos desde el frontend (navegador)?​

¡Sí! Usa la entrada de archivos o arrastrar y soltar.

¿Cómo valido los archivos antes de subir?​

Verifica el tipo de archivo y el tamaño.

¿Puedo obtener una lista de todos los archivos subidos para una entidad?​

No directamente con este SDK. Necesitas:

  1. Rastrear los nombres de archivo al subir (guardar en la base de datos)
  2. Usar la API de Admin de OneEntry para listar archivos

Mejor práctica: Guarda los nombres de archivo subidos en tu base de datos.

¿Cómo manejo los errores de carga?​

Siempre usa try/catch.

¿Puedo subir archivos directamente a CDN?​

No, las cargas pasan a través de la API de OneEntry, que:

  1. Valida el archivo
  2. Optimiza las imágenes (si está habilitado)
  3. Almacena en la nube
  4. Devuelve la URL de CDN

Esto asegura seguridad y optimización.

¿Qué pasa con los archivos si elimino una entidad (producto, usuario)?​

Los archivos permanecen en el almacenamiento incluso si la entidad es eliminada.

Mejor práctica: Elimina los archivos antes de eliminar la entidad.

¿Puedo redimensionar imágenes a dimensiones exactas?​

No, la relación de aspecto siempre se conserva para evitar distorsiones.

Cómo funciona:

  • Estableces width: 800, height: 600
  • La imagen se redimensiona para ajustarse dentro de 800x600
  • La relación de aspecto se conserva

Ejemplo:

Original: 1000x500 (relación 2:1)
Con ancho: 800, altura: 600
Resultado: 800x400 (sigue siendo 2:1, se ajusta dentro de 800x600)

💡 Notas Importantes​

Seguridad de Archivos​

Los archivos subidos son accesibles públicamente a través de CDN:

  • ✅ Genial para imágenes, documentos públicos
  • ⚠️ No subas archivos sensibles (contraseñas, datos privados)

Para archivos privados:

  • Usa la API de Admin de OneEntry con autenticación
  • O implementa tu propio control de acceso

Límites de Almacenamiento​

Monitorea tu uso de almacenamiento:

  • Cada plan tiene límites de almacenamiento
  • Limpia archivos no utilizados regularmente
  • Comprime imágenes antes de subir

Consejos de Optimización de Imágenes​

Para obtener los mejores resultados:

  • ✅ Sube originales de alta calidad (deja que OneEntry optimice)
  • ✅ Usa compress: true para imágenes web
  • ✅ Establece dimensiones apropiadas (por ejemplo, 1920px para imágenes principales, 500px para miniaturas)
  • ❌ No subas imágenes ya comprimidas (pérdida de calidad)

Tamaños recomendados:

  • Fotos de perfil: 500x500
  • Imágenes de productos: 1920x1920
  • Banners principales: 1920x1080
  • Miniaturas: 300x300

🎓 Mejores Prácticas​

  • Valida el tipo de archivo y el tamaño antes de subir
  • Asocia archivos con IDs de entidad para organización
  • Habilita la compresión para imágenes web
  • Maneja los errores de carga de manera adecuada
  • Guarda los nombres de archivo para eliminar archivos más tarde
  • Limpia archivos no utilizados regularmente
  • Muestra el progreso de carga a los usuarios

Definición del módulo FileUploading​


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 Documentación Relacionada​