Subidas de archivos con React y Uppy: reanudación, vistas previas, validación y procesamiento

Define qué significa «completo» antes de escribir el componente

Un navegador puede terminar de enviar los bytes mientras los archivos multimedia resultantes aún se inspeccionan, transforman y exportan. Decide qué estado considera completado la interfaz: la selección del archivo, la transferencia, la creación de la Assembly, el procesamiento, el almacenamiento persistente o la publicación en la aplicación. Los tres niveles siguientes agrupan la selección del archivo y la transferencia bajo el éxito de la transferencia; la creación de la Assembly y el procesamiento, bajo el éxito del procesamiento; y el almacenamiento persistente y la publicación, bajo el éxito de la aplicación. Un componente de React puede mostrar varios de estos estados, pero no debe reducirlos a un único indicador de éxito.

En un flujo de trabajo de Transloadit, Uppy controla la cola y el estado de la transferencia en el navegador. El plugin de Transloadit crea una Assembly y asocia cada archivo local con ese flujo de trabajo. Tu aplicación debe conservar el ID de la Assembly en cuanto exista y, si el procesamiento puede durar más que la página, conciliar el resultado terminal fuera del componente. Una barra de progreso completa no es un registro persistente del recurso.

Crea una instancia configurada de Uppy por cada componente de subida montado

Instala Core, Dashboard, el paquete de la interfaz de React, el plugin de Transloadit con mantenimiento activo y el validador de esquemas Zod para la respuesta de autorización. Importa cada hoja de estilos de Uppy una vez desde un punto de entrada estable para que su orden de carga sea predecible. El siguiente ejemplo de componente importa directamente los estilos del paquete; mueve esas importaciones al punto de entrada de la aplicación si allí es donde tu framework o empaquetador gestiona los estilos globales.

Construye Uppy una vez para toda la vida útil del formulario montado. Un inicializador diferido de useState en la siguiente sección proporciona a cada componente de subida montado su propia instancia sin reconstruirla durante cada nuevo renderizado. No crees un singleton compartido en el nivel del módulo, a menos que todas las superficies formen intencionalmente una única cola; de lo contrario, los formularios independientes verían y eliminarían los archivos de los demás.

La función asíncrona assemblyOptions solicita autorización a un endpoint de confianza inmediatamente antes de la subida. El endpoint debe autenticar y autorizar al usuario actual, aplicar controles contra abusos, elegir un Template restringido y devolver un payload firmado de corta duración. El navegador valida la estructura de la respuesta, pero nunca recibe el Auth Secret.

yarn add @uppy/core @uppy/dashboard @uppy/react @uppy/transloadit zod

import Uppy from '@uppy/core'
import Transloadit from '@uppy/transloadit'
import { z } from 'zod'

const assemblyOptionsSchema = z.object({
  params: z.string().min(1),
  signature: z.string().regex(/^(sha1|sha256|sha384):[0-9a-f]+$/),
})

async function fetchAssemblyOptions(): Promise<z.infer<typeof assemblyOptionsSchema>> {
  const response = await fetch('/api/transloadit-params', {
    method: 'POST',
    headers: { Accept: 'application/json' },
  })

  if (!response.ok) {
    throw new Error('Could not authorize this upload')
  }

  const responseBody: unknown = await response.json().catch(() => null)
  const parsedOptions = assemblyOptionsSchema.safeParse(responseBody)
  if (!parsedOptions.success) {
    throw new Error('Could not authorize this upload')
  }

  return parsedOptions.data
}

export function createImageUploader(): Uppy {
  return new Uppy({
    autoProceed: false,
    restrictions: {
      allowedFileTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxFileSize: 50 * 1024 * 1024,
      maxNumberOfFiles: 5,
    },
  }).use(Transloadit, {
    assemblyOptions: fetchAssemblyOptions,
    retryDelays: [0, 1_000, 3_000, 5_000],
    waitForEncoding: false,
  })
}

Muestra desde Uppy el progreso, la cancelación y el estado de la Assembly

Uppy es un almacén de estado externo. useUppyState suscribe React a valores seleccionados sin mantener una segunda cola en el estado del componente, mientras que useUppyEvent expone eventos que no son campos persistentes del almacén. El componente obtiene el número de archivos, el progreso agregado, el estado de la subida activa, el estado de error sin procesar y el evento de creación de la Assembly. Asigna el error a un mensaje estable para el usuario en lugar de mostrar el valor sin procesar, y no refleja los archivos individuales en un valor useState separado.

Dashboard permite seleccionar archivos, arrastrarlos y soltarlos, obtener vistas previas de los archivos locales compatibles, consultar el estado de cada archivo y usar los controles de subida. La región en vivo independiente proporciona a la aplicación circundante un anuncio conciso del estado, y el botón nativo deshabilitado indica si la cancelación está disponible. Mantén localizadas las etiquetas de Dashboard cuando el producto admita varios idiomas; aplica el mismo tratamiento al encabezado, el estado y los errores circundantes.

Destruye la instancia de Uppy cuando se desmonte el componente al que pertenece. Al destruirla, se cancela el trabajo en curso, se eliminan los plugins instalados y se liberan los listeners. Por lo tanto, un cambio de ruta no debería ser el único lugar donde se conserve el progreso importante: guarda el ID de la Assembly y cualquier registro de tareas de la aplicación antes de depender de trabajo que pueda continuar en otro lugar.

import type { ReactNode } from 'react'

import Dashboard from '@uppy/react/dashboard'
import { useUppyEvent, useUppyState } from '@uppy/react'
import { useEffect, useState } from 'react'

import { createImageUploader } from './createImageUploader.ts'

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

export function ReactFileUploader(): ReactNode {
  const [uppy] = useState(createImageUploader)
  const error = useUppyState(uppy, (state) => state.error)
  const fileCount = useUppyState(uppy, (state) => Object.keys(state.files).length)
  const isUploading = useUppyState(
    uppy,
    (state) => Object.keys(state.currentUploads).length > 0,
  )
  const progress = useUppyState(uppy, (state) => state.totalProgress)
  const [assemblyCreatedArgs, clearAssemblyCreated] = useUppyEvent(
    uppy,
    'transloadit:assembly-created',
  )
  useUppyEvent(uppy, 'cancel-all', clearAssemblyCreated)
  const [assembly] = assemblyCreatedArgs
  const assemblyId = assembly?.assembly_id

  useEffect(() => {
    return () => uppy.destroy()
  }, [uppy])

  let status = 'Choose up to five JPEG, PNG, or WebP images.'
  if (fileCount > 0) status = 'Ready to upload.'
  if (isUploading) status = `Upload ${progress}% complete.`
  if (!isUploading && progress === 100) status = 'Files transferred. Processing may continue.'
  if (error != null) status = 'Upload failed. Check the selected files and try again.'

  return (
    <section aria-labelledby="file-upload-heading">
      <h2 id="file-upload-heading">Upload images</h2>
      <Dashboard height={420} uppy={uppy} />
      <p aria-live="polite" role="status">
        {status}
      </p>
      {assemblyId != null ? (
        <p>
          Processing reference: <code>{assemblyId}</code>
        </p>
      ) : null}
      <button disabled={fileCount === 0} onClick={() => uppy.cancelAll()} type="button">
        Cancel and remove files
      </button>
    </section>
  )
}

Usa las vistas previas y las restricciones como funciones de la interfaz, no como límites de confianza

Una vista previa local ayuda a detectar una selección incorrecta antes de incurrir en el costo de la subida. No es el resultado procesado ni demuestra que el archivo sea seguro, decodificable, esté orientado correctamente o tenga una etiqueta veraz. Limita el trabajo de la vista previa, ya que decodificar muchas imágenes grandes consume memoria del navegador. Para los formatos que el navegador no pueda previsualizar, muestra el nombre del archivo, el tipo declarado y el tamaño sin inventar una miniatura.

Las restricciones de Uppy rechazan pronto los errores evidentes: tipos permitidos, tamaño individual, tamaño total y cantidad de archivos. Repite los mismos límites en un receptor de confianza o en el Template guardado, porque quien realiza la llamada puede eludir React y modificar los metadatos del archivo. Usa el contenido detectado y un intento de procesamiento cuando corresponda; después, almacena únicamente los resultados aceptados. allow_steps_override debe permanecer desactivado cuando el navegador no deba sustituir el flujo de trabajo aprobado. Cuando una vista previa o una restricción rechace una selección, muestra un mensaje estable para el usuario y mantén fuera de la página las respuestas sin procesar del proveedor, las trazas de pila, las credenciales y los diagnósticos del almacenamiento.

Diseña la reanudación según la interrupción que necesites superar

El plugin de Transloadit sube archivos locales mediante el protocolo tus, que puede continuar una transferencia fallida desde un desplazamiento confirmado por el servidor mientras el recurso de subida siga siendo válido. retryDelays gestiona un conjunto limitado de fallos transitorios durante la vida útil de la instancia actual de Uppy. La cancelación es diferente: cancelAll() interrumpe intencionalmente el trabajo en curso, elimina los archivos y restablece el estado de subida, por lo que la interfaz debe indicar que se eliminará la selección.

Recargar la página destruye el estado en memoria de React y Uppy. La recuperación tras una recarga requiere un estado persistente en el cliente y recursos de subida compatibles en el servidor, como un flujo de trabajo con el plugin Golden Retriever configurado deliberadamente. Prueba ese comportamiento con la integración real de Transloadit antes de prometerlo. Los metadatos locales persistentes pueden quedar obsoletos, ser sensibles o no coincidir con una autorización vencida, por lo que debes definir su retención y una forma de descartar las entradas irrecuperables.

La capacidad de reanudar también tiene un plazo operativo. Una Assembly no puede admitir subidas indefinidamente, y los parámetros firmados de corta duración pueden vencer antes de que comience un reintento demorado. Distingue entre el reintento automático, pausar y reanudar, restaurar tras una recarga e iniciar una nueva Assembly; resuelven fallos diferentes y pueden reutilizar identificadores distintos.

Entrega los archivos transferidos a un flujo de trabajo multimedia asíncrono

Un Template guardado debe describir el grafo de procesamiento permitido: /upload/handle recibe los archivos del navegador, /file/filter puede rechazar las entradas observadas no compatibles, los Robots de transformación generan derivados acotados y los Robots de almacenamiento exportan los resultados aprobados cuando el flujo de trabajo incluye almacenamiento persistente. La solicitud firmada selecciona ese Template; React no construye Steps arbitrarios ni transporta credenciales de almacenamiento permanentes.

Elige waitForEncoding según el contrato de la interfaz. Establecerlo en false permite que el navegador finalice después de la transferencia y es apropiado cuando la aplicación registra el ID de la Assembly, muestra un estado de procesamiento independiente y obtiene el resultado final mediante una Assembly Notification verificada o una consulta posterior de Assembly Status. Esperar la codificación puede mantener la interfaz alineada con un procesamiento breve, pero no sustituye una conciliación persistente si se cierra la pestaña.

Almacena el contexto de la aplicación junto al ID de la Assembly: usuario autenticado o inquilino, espacio previsto para el recurso, ID del Template, hora de creación y operación de la aplicación que la originó. Cuando llegue una notificación, verifica su firma, gestiona las entregas duplicadas de forma idempotente, confirma que la Assembly pertenezca al registro esperado y guarda solo los campos de resultados que necesite el producto.

Prueba el ciclo de vida y el comportamiento ante fallos, no solo el caso ideal

Prueba el componente con un archivo pequeño permitido, un archivo demasiado grande, una extensión engañosa, un tipo no compatible, varios archivos en el límite de cantidad, una entrada de cero bytes, una conexión lenta, un intervalo sin conexión, un rechazo del servidor, el vencimiento de la autorización, una cancelación del usuario, el desmontaje del componente y una recarga de la página. Confirma qué estado se conserva, qué trabajo se cancela y qué mensaje recibe un usuario de teclado o lector de pantalla.

Prueba la ruta real de firma y procesamiento, además del comportamiento aislado de React. Una simulación puede demostrar que el botón se deshabilita o que cambia un estado, pero solo un caso de prueba integrado demuestra que los parámetros firmados coinciden, que el protocolo tus reanuda la transferencia desde el desplazamiento esperado, que el Template rechaza el contenido incorrecto, que se registra el ID de la Assembly y que la finalización se concilia una sola vez. Mantén pequeños los archivos de prueba y elimina los datos temporales de producción después de la ejecución.