Mostrando PDFs en Aplicaciones Vue 3

Integrar un PDF dentro de una SPA de Vue 3 suena sencillo—hasta que te encuentras con tu primer error CORS, descubres que el navegador lo renderiza de manera diferente en Safari, o te das cuenta de que tu documento de 200 páginas está bloqueando el hilo principal. Este artículo cubre los tres enfoques prácticos que los desarrolladores realmente utilizan para mostrar PDFs en Vue 3, con ventajas y desventajas honestas para cada uno.

Los Tres Enfoques Principales

1. Incrustación Nativa del Navegador: <iframe> o <embed>

La forma más rápida de mostrar un PDF en pantalla es delegarlo al renderizador de PDF integrado del navegador.

<template>
  <iframe
    :src="pdfUrl"
    width="100%"
    height="700px"
    style="border: none"
  />
</template>

<script setup lang="ts">
const pdfUrl = '/documents/report.pdf'
</script>

Cuándo funciona bien: Herramientas internas, paneles de administración, o cualquier contexto donde la consistencia de UI no sea crítica y el PDF se sirva desde el mismo origen.

Las limitaciones reales:

• Cero control sobre la barra de herramientas, controles de zoom o tematización
• El comportamiento varía entre navegadores—Chrome, Firefox y Safari renderizan de manera diferente
• Los navegadores móviles a menudo descargan el archivo en lugar de mostrarlo en línea
• El estado de carga es invisible para tu componente Vue, por lo que no puedes mostrar un spinner o manejar errores de manera elegante

Si estás cargando un PDF desde un dominio diferente, el navegador bloqueará la solicitud a menos que el servidor envíe los encabezados Access-Control-Allow-Origin correctos. Un endpoint proxy del mismo origen en tu backend es la solución más limpia.

2. PDF.js con Vue 3: Integración Directa

PDF.js es el motor de renderizado de PDF de código abierto de Mozilla. A partir de la serie de versiones 5.x, se distribuye como un paquete ESM-first. Importas desde build/pdf.mjs y cargas un worker separado (pdf.worker.mjs) para mantener el renderizado fuera del hilo principal.

npm install pdfjs-dist

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import * as pdfjsLib from 'pdfjs-dist/build/pdf.mjs'

pdfjsLib.GlobalWorkerOptions.workerSrc = new URL(
  'pdfjs-dist/build/pdf.worker.mjs',
  import.meta.url
).toString()

const canvasRef = ref<HTMLCanvasElement | null>(null)

onMounted(async () => {
  const pdf = await pdfjsLib.getDocument('/documents/report.pdf').promise
  const page = await pdf.getPage(1)
  const viewport = page.getViewport({ scale: 1.5 })
  const canvas = canvasRef.value!
  const ctx = canvas.getContext('2d')!
  canvas.height = viewport.height
  canvas.width = viewport.width
  await page.render({ canvasContext: ctx, viewport }).promise
})
</script>

<template>
  <canvas ref="canvasRef" />
</template>

Lo que ganas: Control total sobre el renderizado, navegación de páginas, zoom y tematización. PDF.js soporta anotaciones estándar y campos AcroForm, aunque el comportamiento de formularios y anotaciones puede depender de la configuración de renderizado.

Lo que debes saber:

• El paquete pdfjs-dist añade una carga notable a tu bundle del cliente. Usa import() dinámico para cargarlo de forma diferida.
• Los formularios basados en XFA (comunes en PDFs gubernamentales antiguos) tienen soporte limitado y pueden no renderizarse correctamente.
• Para documentos grandes, PDF.js puede obtener PDFs en fragmentos cuando el servidor soporta solicitudes de rango HTTP (Accept-Ranges: bytes), lo que puede mejorar el rendimiento percibido para archivos grandes.
• La configuración del worker es el problema de configuración más común en proyectos Vite. El patrón new URL(..., import.meta.url) mostrado arriba resuelve la ruta del worker correctamente en tiempo de compilación.

3. Wrappers de Vue PDF

Varios componentes de Vue 3 mantenidos envuelven PDF.js y exponen una API de componente más simple. vue-pdf-embed es una opción mantenida activamente que maneja la configuración del worker, el renderizado de páginas y las actualizaciones de props reactivas por ti.

<script setup lang="ts">
import VuePdfEmbed from 'vue-pdf-embed'
</script>

<template>
  <VuePdfEmbed source="/documents/report.pdf" />
</template>

El compromiso es menos control granular a cambio de significativamente menos código repetitivo. Estos wrappers son una buena opción cuando necesitas un visor de PDF de Vue 3 funcionando rápidamente y no necesitas personalizar el pipeline de renderizado.

Nota: Algunos paquetes más antiguos como vue3-pdf-app ya no se mantienen activamente. Evalúa el estado de mantenimiento y compatibilidad de cualquier wrapper con bundlers modernos como Vite antes de adoptarlo.

Eligiendo el Enfoque Correcto

Conclusión

Para la mayoría de las aplicaciones Vue 3, la decisión es directa: usa <iframe> para incrustaciones simples del mismo origen, recurre a un wrapper de Vue mantenido cuando necesites un visor funcionando sin mucha configuración, e integra PDF.js directamente cuando necesites control total sobre el renderizado, navegación o rendimiento para documentos grandes. Cualquiera que sea el camino que elijas, configura el worker de PDF.js correctamente y carga la librería de forma diferida. Solo esos dos pasos prevendrán los problemas más comunes que los desarrolladores encuentran al incrustar PDFs en aplicaciones Vue.

Preguntas Frecuentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.